Expose the HTTP server to module loaders (ContainerRegistrationKeys.HTTP_SERVER)

[Gustavitory]

Summary

Register the http.Server created by medusa start in the container under a new key, ContainerRegistrationKeys.HTTP_SERVER, and pass it to module loaders as a default dependency. This lets modules and plugins attach to the server (WebSocket, Socket.IO, GraphQL subscriptions, etc.) without patching Node internals.

Problem

In packages/medusa/src/commands/start.ts the server is created before loaders() runs, but it only lives in a local variable (http_). Module loaders have no way to reach it.

Today the only workaround is monkey-patching http.createServer from instrumentation.ts to capture the first server Medusa creates. I described this approach in #15299 and we have been running it in production (multi-instance, Socket.IO with the Redis adapter). It works, but it is fragile:

• It depends on instrumentation.ts running before createServer, which is an implementation detail.
• It requires global state (globalThis) to hand the server from the instrumentation hook to the module loader.
• It has to guess the execution context (server, worker, medusa exec, migrations) through environment variables.

Proposal

1. Add HTTP_SERVER: "httpServer" to ContainerRegistrationKeys.

2. Register the server right after it is created in start.ts, before loaders():

   container.register(ContainerRegistrationKeys.HTTP_SERVER, asValue(http_))

3. Add ContainerRegistrationKeys.HTTP_SERVER to the default dependencies passed to every module's local container in load-internal.ts, next to LOGGER, CONFIG_MODULE, etc.

4. Type it in ModuleImplementations as Server | undefined.

Usage

export default async function realtimeLoader({ container, options }: LoaderOptions) {
  const server = container.resolve(ContainerRegistrationKeys.HTTP_SERVER, {
    allowUnregistered: true,
  })
  const { projectConfig } = container.resolve(ContainerRegistrationKeys.CONFIG_MODULE)

  if (!server || projectConfig.workerMode === "worker") {
    return
  }

  const io = new Server(server, { path: "/socket.io" })
}

• In medusa exec, migrations or build, the key is not registered, so server resolves to undefined and the loader skips.
• Loaders run before listen(), so attaching here is safe.

Backward compatibility

Purely additive: one new key and one extra registration. No behavior changes for existing apps, modules or plugins.

Implementation

The change is ready on my fork, a 7-line diff plus a changeset, and builds cleanly:
https://github.com/Gustavitory/medusa/tree/feat/http-server-container-key

Open questions

• Is httpServer / HTTP_SERVER a good name, or would you prefer something else?
• In worker mode the server is still created (it serves /health). I left it registered there and let modules decide based on projectConfig.workerMode. Would you rather not register it in worker mode?
• Should this come with an integration test and a docs entry? Happy to add both.

Follow-up

Once this lands, I'd like to propose an optional realtime module (Socket.IO, configured through medusa-config, with a Redis adapter for multi-instance), following the same opt-in pattern as the Caching module. I can open a separate discussion for it.

I'd like to be assigned to the issue and open the PR.

[Gustavitory]

#15299