server

Overview ¶

build_services.go — factory for per-workspace WorkspaceServices.

Extracted from internal/cmd/serve.go as part of multi-tenant bcd phase M2. A single call to BuildWorkspaceServices(ctx, globals, wsRoot) produces a fully-initialized WorkspaceServices bundle including background goroutines. Its Close() cancels those goroutines and closes each store.

The factory depends ONLY on Globals + a workspace root path, so it can be invoked at any time for any registered workspace — which is the substrate for multi-workspace dispatch (phases M5-M6).

legacy_scope.go — 301 redirects for un-scoped UI paths.

The multi-workspace UI lives under /w/<wsId>/<page>. Older bookmarks hit /<page> directly and the SPA used to resolve them against the active workspace. After the /w/<wsId>/... canonicalization (see multi-workspace-and-code-tab.md §5.1 and §9.2–9.3) those un-scoped URLs should issue a permanent redirect to the active workspace's canonical URL, with Deprecation / Sunset headers so link-following clients can log the rename.

Scope: this middleware only rewrites the top-level SPA pages, not their subpaths that are served by /api/ or /_mcp/, which are handled by WorkspaceScope and the MCP dispatcher. If there is no active workspace in the registry we pass through — the SPA will show its "pick a workspace" CTA.

mcp_compat.go — backward-compat shim for pre-M6 MCP SSE URLs.

The canonical MCP endpoint lives at /_mcp/ws/<wsID>/<agent>/{sse,message} (see mcp_dispatch.go). Agents spawned before phase M6 were configured against the un-scoped /_mcp/<agent>/{sse,message} path, which was mounted directly against the launch workspace.

This middleware rewrites those legacy paths to the scoped form using the active workspace ID so the /_mcp/ws/ dispatcher serves them, and stamps Deprecation / Sunset response headers so anyone tailing logs can see which agent configurations still need updating. An internal URL rewrite is used rather than an HTTP 308 because streaming SSE clients are not reliably redirect-following on the initial GET.

Paths that are already scoped, or that address the MCP discovery / .well-known surface, pass through untouched. If there is no active workspace in the registry we also pass through — the existing legacy mount at /_mcp/<agent>/... continues to target the launch workspace as before.

mcp_dispatch.go — scoped MCP SSE routing for multi-workspace bcd.

Introduced in phase M6: the canonical MCP endpoint becomes

/_mcp/ws/<wsID>/<agent>/{sse,message}

dispatched per-request by the WorkspaceManager. Each loaded workspace maintains its own MCP server instance (built lazily on first scoped call). Legacy /_mcp/<agent>/* paths continue to target the launch workspace's server for backward compatibility with agents that were spawned before the path scheme changed.

Package server implements the bcd HTTP API server.

The server exposes workspace state over HTTP so the bc CLI can operate as a thin client. It binds to localhost only by default and serves:

• REST API at /api/… (JSON, one handler file per resource)
• SSE stream at /api/events (real-time agent state updates)
• Static web UI at / (embedded web/dist, served when built)
• Health probe at /health

Default address: 127.0.0.1:9374

stats_collector.go — per-workspace background metric collectors.

Split out of internal/cmd/serve.go in phase M2 so the factory in build_services.go can start these goroutines as part of a WorkspaceServices lifecycle. Behavior is identical to the prior implementation; only the package boundary changed.

workspace_scope.go implements URL-level workspace scoping middleware.

Overview ========

The bcd server historically exposes every resource at /api/<resource>/... bound to a single workspace. With multi-workspace support the proposal introduces two URL schemes:

/api/workspaces/{id}/<rest>     — scoped (canonical, post-migration)
/api/<rest>                     — legacy (active workspace shim)

The middleware in this file performs two jobs:

1. Scoped rewrite: if the path matches /api/workspaces/{id}/<rest> AND {rest} is NOT empty AND NOT a registry-management route (detail, activate, etc.), rewrite the request's URL.Path to /api/<rest> and annotate the request context with the resolved WorkspaceServices. Existing handlers continue to use their closure-captured services (the active workspace's). If the {id} is the active workspace, this is a no-op rewrite and everything works. If {id} is a different registered workspace, we return 501 Not Implemented — full per- workspace handler dispatch is a future phase; switch via POST /api/workspaces/{id}/activate.

2. Legacy headers: if the path starts with /api/ but NOT /api/workspaces, the response is annotated with Deprecation: true and a Sunset date so clients can warn when they are still using the old shape. The handler chain is unchanged (handlers serve the active workspace as before).

This split keeps the heavy refactor — per-workspace handler trees — for a later phase while delivering the URL surface specified in proposal §4.5.

Package server — workspace_services.go provides per-workspace service bundling and a lazy-loading manager so bcd can hold multiple workspaces open simultaneously.

The existing `Services` struct (server.go) is the flat dependency bundle used by the handler constructors. `WorkspaceServices` wraps that with a `Workspace` reference plus a closer so the manager can shut down a workspace cleanly on eviction.

Call flow:

bcd boot
  → NewWorkspaceManager(registry, factory)
  → mgr.LoadActive(ctx)          // eager-load the active workspace
  → handler: mgr.Get(id) or mgr.Load(ctx, id)  // lazy-load on demand
  → background goroutine every ~1m evicts idle entries after 30m

The factory is injected so internal/cmd/serve.go can supply the real initialization code (stats store, cron scheduler, gateway manager, etc.) without this package depending on it.