Discovery Handshake Protocol Reference

The Discovery Handshake is a hybrid mechanism that enables zero-config federation. It combines Startup Broadcasts for local discovery and a JIT Oracle for lazy resource resolution in distributed environments.

The Discovery Oracle (JIT)

In Macroservice mode, the framework avoids large, noisy broadcasts in favor of a lazy "Oracle" query. When the frontend needs a resource whose owner is unknown, it pings the Gateway's discovery endpoint.

Backend API (Gateway Oracle)

These endpoints are provided by the GatewayController to support JIT discovery.

GET /api/gateway/remotes

Returns the complete map of MFE remote entries known to the gateway.

• Response: Record<string, DiscoveryUnit>

POST /api/gateway/discovery/query

Batch resolution for DocType ownership.

• Request:

  {
    "resources": ["string"], // List of DocTypes to resolve (e.g., "sales.Invoice")
    "services": { "service_name": 0 } // Optional: list of services to fetch full manifests for
  }

• Response:

  {
    "resources": { "sales.Invoice": "finance" },
    "services": { "finance": { "url": "...", "apiUrl": "..." } }
  }

GET /api/gateway/discovery/{resource}

Single resource owner resolution.

• Response: {"owner": "service_name"}

---

Technical Reference: DiscoveryClient (SDK)

The DiscoveryClient is a frontend singleton that manages the lifecycle of the handshake.

Singleton Lifecycle

• Access: DiscoveryClient.get_instance()
• Initialization: Typically triggered during the Shell's prewarmCore phase.
• Testing: Must call reset() in afterEach hooks to prevent state leakage between unit tests.

Resource Resolution Flow

1. Cache Check: Look up the DocType owner in the local PluginRegistry.
2. Batching: If missing, add the resource to the pending discovery queue.
3. The Oracle Call: Execute a POST to the gateway discovery oracle.
4. Hydration: Update the PluginRegistry with the returned owners and update the DiscoveryClient manifest cache with service URLs.

Parallel Warming (prewarm)

The prewarm(services: string[]) method allows the shell to warm multiple core services in parallel during bootstrap. It uses Promise.allSettled to ensure the shell remains resilient even if non-critical services fail to resolve.

---

Desk Routes & Asset Serving

The backend provides specialized routes for serving the Desk shell and MFE assets.

HTML Hydration: __FRAMEWORK_CONFIG__

The /desk/ route injects a configuration payload into the index.html before serving. This allows the shell to be "zero-conf" and aware of its environment (Monolith vs Macroservice) before the JS bundle executes.

Hybrid Asset Resolution (serve_mfe_assets)

When an MFE asset is requested (e.g., /desk/assets/finance/remoteEntry.js):

1. Local Search: The backend checks for the asset in the local Python package's static/mfe directory using importlib.resources.
2. Proxy Fallback: If FRAMEWORK_M_MFE_PROXY_ENABLED is true, the backend proxies the request to the remote service's apiUrl.
3. Regex Rewriting: Asset URLs in the shell's HTML are automatically rewritten to ensure they point to the correct /desk/assets/ prefix.

Deterministic Routing

The X-Framework-M-Service header is used to ensure that requests are routed to the correct macroservice. The frontend automatically injects this header based on the resolved resource owner.

---

Startup Broadcasts (Legacy)

The framework still supports event-driven broadcasts for environments where NATS or a shared bus is the primary source of truth.

• Topic: infra.schema.discovery
• Event Type: schema.broadcast

Discovery Unit Schema

Field	Type	Description
url	string	Full URL to the remote entry script (remoteEntry.js).
apiUrl	string	The base URL for all data operations for this service.
metaUrl	string	The endpoint for fetching UI metadata (DocTypes, Menus).
openapiUrl	string	(Optional) URL to the OpenAPI spec for the service.

| Mode | Discovery Mechanism | | :--- | :--- | :--- | | MONOLITH | Auto-scans INSTALLED_APPS for static/mfe/remoteEntry.js. | | MACROSERVICE | Uses the JIT Oracle backed by NATS JetStream KV for manifest synchronization. |