Protected OptionalconfigProtected ReadonlycontributionsProtected ReadonlydocumentProtected ReadonlyloggerProtected OptionalmainRouter serving the contributions on the main HTTP server with samePort delivery.
ProtectedpendingSerializes configuration updates to avoid concurrent server starts/stops.
Protected ReadonlyresponseProtected ReadonlyrouterProtected OptionalserverProtected ReadonlytoThe contribution routers of the current routing build. Disposed before the next build and on shutdown, so that long-lived connections such as event streams are closed and clients reconnect against the new configuration.
ProtectedapplyProtectedcheckProtectedcheckRejects requests carrying an Origin header with 403. Such requests come from a browser
context, and browsers execute CORS-simple cross-origin requests before any preflight, so a
malicious page could otherwise drive state-changing routes, most notably with samePort
delivery, where the external API shares the main server's port. The main server's
cookie-based HttpConnectionValidator cannot protect these routes because external tools
never hold the connection-token cookie; such tools do not send an Origin header either,
so they are unaffected by this guard.
Called after the initialization of the backend application is complete. Use this to configure the Express app before it is started, for example to offer additional endpoints.
The implementation may be async, however it will still block the configuration step until it's resolved.
the express application to configure.
either undefined or a Promise resolving to undefined.
ProtectedcreateProtecteddescribeDescribes where the external API is served, for log messages.
ProtectedfindReturns a mounted path that nests with the candidate path, i.e. one is a path-segment
prefix of the other, or undefined when the candidate nests with no mounted path.
The root path / nests with every path, as everything is below it.
ProtectedisWhether the hostname only accepts connections from the local machine.
ProtectedisWhether the segments start with all of the prefix segments, i.e. whether the prefix path contains them.
ProtectedlogProtectedmatchesCalled when the backend application shuts down.
When shutdown is initiated via SIGINT/SIGTERM, contributions are dispatched
in parallel and any returned promise is awaited up to SHUTDOWN_TIMEOUT_MS
milliseconds while injected services from the root container are still
resolvable.
On synchronous-exit fallback paths (uncaught exceptions, server bind failures, or normal process exit), the hook is invoked synchronously and any returned promise is discarded. Implementations should be resilient to either path.
Contributions must be independent of one another during stop because they are dispatched in parallel.
ProtectedpathSplits a path into its non-empty segments, e.g. /api/ai/ into ['api', 'ai'].
ProtectedstartProtectedstop
Serves the ExternalApiContributions, either on a dedicated HTTP server or on Theia's main HTTP server, as configured by the external API preferences pushed by the frontend. It is off by default, applies configuration changes immediately, and protects contributions by bearer token verification when a token is configured (unless they opted out).
The external API is for external tools, not for browser pages: requests carrying an
Originheader are rejected so that web pages cannot drive the API cross-origin, see checkCrossOrigin.The configuration applies to the backend as a whole: when several frontends are connected, the configuration pushed last wins, and it stays in effect until it is changed or the backend stops. It is not revoked when the frontend that pushed it disconnects.
The dedicated server allows external tools to consume Theia APIs independently of the main server's frontend-oriented protections. In Electron deployments the main port requires the Electron security token, so
samePortdelivery is not reachable for external processes there without further customizations. WithsamePortdelivery, contribution paths share the main server's path space: a contribution answers everything below its path, so a path that nests with one of Theia's own routes shadows it.