The Theia data bridge is a VSCode extension allowing injecting and retrieving data. The injection is done via HTTP requests from the VSCode host and the retrieval is handled using VSCode commands.
The extension exposes a lean HTTP server running on 0.0.0.0:16281. Set DATA_BRIDGE_PORT to use another port; a value that is not a number from 1 to 65535 falls back to 16281.
It offers an endpoint POST /data to inject data.
It will store those data in memory and offer them to other extensions via VSCode commands.
POST /data requires the token of the pool instance the extension runs in. The
server reads the expected value from the DATA_BRIDGE_TOKEN environment variable,
and the caller must present it as a bearer token:
Authorization: Bearer <DATA_BRIDGE_TOKEN>
The operator keeps one random token per prewarmed instance in a Kubernetes Secret,
passes it to the pod as DATA_BRIDGE_TOKEN via secretKeyRef, sends it on every
injection, and writes a new one before the pod restarts for the next session
(EduIDE-Cloud#156, design in EduIDE-Cloud#157). Lazy sessions do not use the data
bridge.
The token is compared in constant time. Requests with a missing or wrong token are
rejected with 401.
After authentication the request is checked: a body that does not match the schema
gets 400, a body over 64 KiB gets 413, and an internal error gets a generic 500
without details.
An injection replaces everything stored before, so the operator can safely repeat a
failed injection. Only known keys are stored: THEIA, TEMPLATE, GIT_URI,
GIT_USER, GIT_MAIL, GIT_REF, GIT_SOURCE, ARTEMIS_URL, ARTEMIS_TOKEN, GRADLE_PREWARM,
GRADLE_PREWARM_AUTO_CONFIRM and THEIACLOUD_SESSION_SECRET. Any other key is
ignored and a warning is logged. The response lists the names of the ignored keys as
{"ignored": [...]} (never the values), and the operator logs them. Deployments that inject further keys (for example from
a ConfigMap) list them, comma separated, in DATA_BRIDGE_EXTRA_KEYS.
The server fails closed: if DATA_BRIDGE_TOKEN is unset (or empty), every
POST /data request is rejected with 401 and a warning is logged at startup.
There is no "no auth" mode.
Roll out the operator and the chart that lets it manage Secrets before this data bridge. An older operator sends no header, so this server would reject every injection.
GET /health stays public so it can be used as a readiness probe.
The listener binds to 0.0.0.0 because the injection caller reaches the server from
another pod over the flat pod network. The token is the access control; a
NetworkPolicy restricting which pods may reach port 16281 is still required as
defence in depth.
The extension exposes a set of VSCode commands to handle retrieval of data.
dataBridge.getEnv- Takes a list of environment variables
- Returns a dictionary of stored environment variables
The extension will store the data in memory and in the VS Code secret storage.
Every browser window starts its own plugin host and its own bridge, and only the first one gets the port. dataBridge.getEnv therefore re-reads the secret storage on every call, so the other windows receive the injected environment too.
The extension uses a centralized logger service (src/service/logger.ts) with an output channel for logging.
Usage:
import logger from "./service/logger";
// Log levels
logger.debug("Detailed debugging info"); // Only shown if log level is DEBUG
logger.info("General information"); // Default level
logger.warn("Warning message"); // Warnings
logger.error("Error occurred", error); // Errors with stack traces
// View logs
// Method 1: Command Palette → "Data Bridge: Show Logs"
// Method 2: View → Output → Select "Data Bridge" from dropdownConfiguration:
Set the log level in VS Code settings:
{
"dataBridge.logLevel": "DEBUG" // Options: DEBUG, INFO, WARN, ERROR
}Guidelines:
- Use
logger.debug()for detailed tracing (e.g., command args, iteration details) - Use
logger.info()for important state changes (e.g., server started, data injected) - Use
logger.warn()for recoverable issues (e.g., 404s, validation warnings) - Use
logger.error()for failures (e.g., server errors, exceptions) - Never use
showInformationMessage()for routine operations—reserve for critical user notifications only
pnpm run testvscode-test downloads and launches a real VS Code instance, so the tests need a display. On a
headless machine (including CI) run them under xvfb-run -a pnpm run test.
The pretest hook compiles the sources with tsconfig.test.json, which is the only place emit is
configured: the main tsconfig.json is type-check only, so the test build overrides it to emit
CommonJS into out/. .vscode-test.mjs then picks up out/test/**/*.test.js.
Renovate keeps dependencies current. renovate.json extends the org-wide preset in
EduIDE/.github, so repo-local config stays minimal.
package.json pins pnpm in packageManager, and CI and Renovate both use that version. Keep it on
pnpm 10 while the overrides live under pnpm.overrides in package.json: pnpm 11 ignores that
field, drops the overrides from the lockfile, and pnpm install --frozen-lockfile then fails with
ERR_PNPM_LOCKFILE_CONFIG_MISMATCH.