Skip to content

About

This repository contains a VSCode extension allowing customization of theia online-IDEs at runtime.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Theia Data Bridge

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.

Architecture

Data Injection

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.

Authentication

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.

Data Retrieval

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

Data Storage

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.

Development

Logging

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 dropdown

Configuration:

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

Testing

pnpm run test

vscode-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.

Dependency updates

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.

About

This repository contains a VSCode extension allowing customization of theia online-IDEs at runtime.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages