@yamf/services-deploy-router 0.1.0 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 mcbrumagin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,25 +1,33 @@
 {
   "name": "@yamf/services-deploy-router",
-  "version": "0.1.0",
+  "version": "0.9.0",
   "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "description": "Registry plugin: deploy-plan + deploy-bundle (slice C3)",
   "main": "service.js",
+  "exports": {
+    ".": "./service.js",
+    "./placement": "./placement.js"
+  },
   "files": [
     "service.js",
     "placement.js"
   ],
   "devDependencies": {
-    "@yamf/test": "0.1.4"
+    "@yamf/test": "0.9.0"
   },
   "license": "MIT",
   "dependencies": {
-    "@yamf/core": "0.8.1"
+    "@yamf/core": "0.9.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/mcbrumagin/yamf"
   },
   "scripts": {
-    "test": "yamf test -d ."
+    "test": "yamf test -d .",
+    "test:all": "yamf test -d . --include-e2e"
   }
 }

package/placement.js

@@ -1,8 +1,8 @@
 import { HttpError } from '@yamf/core'
 
 /**
- * C4: least-loaded pm3 node by `replicaMetadata.node` tallies.
- * @param {{ _state?: { replicaMetadata: Map<unknown, { node?: string }> }, listHealthyLocations?: (name: string) => string[] }} registry
+ * C4: least-loaded pm3 node by `replicaMetadata.nodeId` tallies (legacy `node` still counted if present).
+ * @param {{ _state?: { replicaMetadata: Map<unknown, { nodeId?: string, node?: string }> }, listHealthyLocations?: (name: string) => string[] }} registry
  * @param {string} pm3ServiceName
  * @param {{ excludeNodes?: string[] }} [opts]
  */
@@ -16,8 +16,9 @@ export function pickNode (registry, pm3ServiceName, { excludeNodes = [] } = {})
   if (meta) {
     const load = new Map(nodes.map((n) => [n, 0]))
     for (const [, row] of meta) {
-      if (row?.node && load.has(row.node)) {
-        load.set(row.node, (load.get(row.node) || 0) + 1)
+      const nid = row?.nodeId ?? row?.node
+      if (nid && load.has(nid)) {
+        load.set(nid, (load.get(nid) || 0) + 1)
       }
     }
     return [...load.entries()].sort((a, b) => a[1] - b[1])[0][0]

package/service.js

@@ -9,26 +9,61 @@ import {
 import { existsSync } from 'node:fs'
 import { pickNode } from './placement.js'
 
+const DEPLOY_HISTORY_MAX = 20
+
+function pushDeployEvent (registry, event) {
+  const h = registry?._state?.deployHistory
+  if (!Array.isArray(h)) return
+  h.push(event)
+  if (h.length > DEPLOY_HISTORY_MAX) h.splice(0, h.length - DEPLOY_HISTORY_MAX)
+}
+
+/**
+ * Wire verbs registered by {@link registerDeployRouter}. Exported so CLI / deploy-driver code
+ * can target them without stringly-typed literals.
+ */
+export const DEPLOY_COMMANDS = Object.freeze({
+  /** Server-side rollout decision; takes `{ services: [{ name, hash, replicas? }] }`. */
+  PLAN: 'deploy-plan',
+  /** Streamed bundle upload; body is the raw bundle, `yamf-deploy-hash` header required. */
+  BUNDLE: 'deploy-bundle'
+})
+
 const PLUGIN_SERVICE = 'yamf-deploy-router'
 
 /**
- * @param {object} registry - server from `registryServer()`; must expose `registerCommand`, `getReplicasFor`, optional `_bundleStore`
+ * Install the deploy-router plugin onto a running registry.
+ *
+ * This is a **registry plugin** in the privileged in-process tier (see
+ * `@yamf/core/registry/command-router.js#registerCommand`): handlers run with direct
+ * `getReplicasFor` / `_bundleStore` access *after* token validation. It is **not** a
+ * service factory and is reserved for trusted boot code (CLI dev bootstrap, integration
+ * harnesses). For app-level extension via custom `yamf-command` verbs, see the v1 plan —
+ * service-extended commands are deferred to post-v1.
+ *
+ * Verbs registered: {@link DEPLOY_COMMANDS.PLAN} and {@link DEPLOY_COMMANDS.BUNDLE}.
+ *
+ * @param {object} registry - server from `registryServer()`; must expose `registerCommand`,
+ *   `getReplicasFor`, and (if `bundleStore` is omitted) `_bundleStore`.
  * @param {{ bundleStore?: object, location: string, pm3ServiceName?: string }} options
- * @param {string} options.location - own URL (used for `registerCommand` cleanup key; often `YAMF_REGISTRY_URL`)
+ * @param {string} options.location - Own URL (used as the `registerCommand` cleanup key;
+ *   typically `YAMF_REGISTRY_URL`).
+ * @returns {{ pickNode: (opts?: object) => string }} Helper bound to the registry / pm3 service name.
  */
-export function attachDeployRouter (registry, { bundleStore, location, pm3ServiceName = 'pm3-service' } = {}) {
+export function registerDeployRouter (registry, { bundleStore, location, pm3ServiceName = 'pm3' } = {}) {
   if (!location) {
-    throw new Error('attachDeployRouter: `location` (registry public URL) is required')
+    throw new Error('registerDeployRouter: `location` (registry public URL) is required')
   }
   if (!bundleStore && !registry?._bundleStore) {
-    throw new Error('attachDeployRouter: pass bundleStore or start registry with a bundle store')
+    throw new Error('registerDeployRouter: pass bundleStore or start registry with a bundle store')
   }
   const store = bundleStore || registry._bundleStore
 
-  // Server-side plan (auth: deploy token). The `yamf deploy` CLI still uses REGISTRY_PULL + planAndApply
-  // client-side for parity; keep this for HTTP API consumers and future "registry as source of truth" flows.
+  // Server-side plan (auth: deploy token). The `yamf deploy` CLI still uses REGISTRY_PULL +
+  // planAndApply client-side for parity; this stays for HTTP API consumers and future
+  // "registry as source of truth" flows.
   registry.registerCommand(
-    'deploy-plan',
+    DEPLOY_COMMANDS.PLAN,
     async ({ body, headers }) => {
       const out = { decisions: [] }
       for (const s of body?.services || []) {
@@ -38,18 +73,20 @@ export function attachDeployRouter (registry, { bundleStore, location, pm3Servic
         const reps = registry.getReplicasFor(s.name) || []
         const { decision } = deployDecisionFromReplicas(reps, s.hash, s.replicas ?? 1)
         out.decisions.push({ service: s.name, hash: s.hash, decision })
-        const fromH = (reps || []).map((r) => r.sourceHash).filter(Boolean).join(',') || null
+        const fromHash = reps.map((r) => r.sourceHash).filter(Boolean).join(',') || null
+        const deployEvent = {
+          service: s.name,
+          fromHash,
+          toHash: s.hash,
+          decision,
+          at: Date.now(),
+          deployer: headers[HEADERS.DEPLOYER] || null
+        }
+        pushDeployEvent(registry, deployEvent)
         try {
-          await publishMessage('yamf:deploy', {
-            service: s.name,
-            fromHash: fromH,
-            toHash: s.hash,
-            decision,
-            at: Date.now(),
-            deployer: headers[HEADERS.DEPLOYER] || null
-          })
+          await publishMessage('yamf:deploy', deployEvent)
         } catch {
-          /* no pub */
+          // best-effort observability; missing pubsub does not fail the plan
         }
       }
       return out
@@ -64,7 +101,7 @@ export function attachDeployRouter (registry, { bundleStore, location, pm3Servic
   )
 
   registry.registerCommand(
-    'deploy-bundle',
+    DEPLOY_COMMANDS.BUNDLE,
     async ({ request, headers }) => {
       const hash = (headers[HEADERS.DEPLOY_HASH] || headers['yamf-deploy-hash'] || '').trim()
       if (!hash) {