any-hub/docs/operations/migration.md

Modular Hub Migration Playbook

This playbook describes how to cut a hub over from the shared legacy adapter to a dedicated module using the new rollout flags, diagnostics endpoint, and structured logs delivered in feature 004-modular-proxy-cache.

Prerequisites

• Target module must be registered via hubmodule.MustRegister and expose a proxy handler through proxy.RegisterModuleHandler.
• config.toml must already map the hub to its target module through [[Hub]].Module.
• Operators must have access to the running binary port (default :5000) to query /-/modules.

Rollout Workflow

1. Snapshot current state
   Run curl -s http://localhost:5000/-/modules | jq '.hubs[] | select(.hub_name=="<hub>")' to capture the current module_key and rollout_flag. Legacy hubs report module_key=legacy and rollout_flag=legacy-only.

2. Prepare config for dual traffic
   Edit the hub block to target the new module while keeping rollback safety:

   [[Hub]]
   Name = "npm-prod"
   Domain = "npm.example.com"
   Upstream = "https://registry.npmjs.org"
   Module = "npm"
   Rollout = "dual"
   

   Dual mode keeps routing on the new module but keeps observability tagged as a partial rollout.

3. Deploy and monitor
   Restart the service and tail logs filtered by module_key:

   jq 'select(.module_key=="npm" and .rollout_flag=="dual")' /var/log/any-hub.json
   

   Every request now carries module_key/rollout_flag, allowing dashboards or grep-based analyses without extra parsing.

4. Verify diagnostics
   Query /-/modules/npm to inspect the registered metadata and confirm cache strategy, or /-/modules to ensure the hub binding reflects rollout_flag=dual.

5. Promote to modular
   Once metrics are healthy, change Rollout = "modular" in config and redeploy. Continue monitoring logs to make sure both module_key and rollout_flag show the fully promoted state.

6. Rollback procedure
   To rollback, set Rollout = "legacy-only" (without touching Module). The runtime forces traffic through the legacy module while keeping the desired module declaration for later reattempts. Confirm via diagnostics (module_key reverts to legacy) before announcing rollback complete.

Observability Checklist

• Logs: Every proxy log line now contains hub, module_key, rollout_flag, upstream status, and request_id. Capture at least five minutes of traffic per flag change.
• Diagnostics: Store JSON snapshots from /-/modules before and after each rollout stage for incident timelines.
• Config History: Keep the config.toml diff (especially Rollout changes) attached to change records for auditability.

Troubleshooting

• Error: module_not_found during diagnostics → module key not registered; ensure the module package’s init() calls hubmodule.MustRegister.
• Requests still tagged with legacy-only after promotion → double-check the running process uses the updated config path (ANY_HUB_CONFIG vs --config) and restart the service.
• Diagnostics 404 → confirm you are hitting the correct port and that the CLI user/network path allows HTTP access; the endpoint ignores Host headers, so curl http://127.0.0.1:<port>/-/modules should succeed locally.