Workshop JavaScript Client Library

The Workshop Client library is installed in Codecademy web clients and provides access from those clients to code execution services (Propeller, previously known as Workshop). Propeller manages a persistent websocket connection allowing clients to sync user code, execute that code in a variety of server environments, run terminal commands, and perform other code/workspace management and execution actions.

Testing changes locally

1. Check out both this repo and the Codecademy repo
2. Run yarn build in the workshop-client directory
3. Run yarn link in the workshop-client directory
4. In the monorepo, run yarn link @codecademy/workshop-client
5. Run (or re-run) yarn nx start learning-environment in the monorepo
6. Verify that you can connect to the LE in your local branch. If you continue to make changes in the client, you'll need to re-yarn build and restart the LE application.

Starting a session

To start a session, create a client instance and connect to workshop.

import WorkshopSession from '@codecademy/workshop-client';

let session = new WorkshopSession({
  protocol: 'https',
  apiBase: 'effective-lamp.cc-propeller.cloud',
  workspaceSlug: 'my-workspace',
  jwt: 'my.user.jwt',
});

session
  .initialize()
  .then(() => {
    // Ready to use
  })
  .catch(error => {
    // Something went wrong
  });

Tracing

The client works with OpenTelemetry tracing, and needs @opentelemetry/api 1.x installed alongside it. Calls to Container API join whatever span is active when you call initialize() or delete():

• Each request to Container API runs in that span's context. The app's fetch instrumentation then records it as a child span and sends traceparent, so Container API's spans join the same trace.
• The socket handshake carries traceparent and tracestate as query parameters, because a browser can't set headers on a WebSocket handshake. Only the handshakes made while initialize() waits for the socket to open carry them. A reconnect after that starts a trace of its own.

The client saves the context when the call starts. In the browser, OpenTelemetry tracks the active span with zone.js, which loses it at the first native await, so requests sent later in the call would otherwise start traces of their own. With no tracing set up, the requests and the socket URL are unchanged.

Publishing the package

This package is automatically published when the version number changes

• merge your PR into main
• create a new PR that updates the version of the package in package.json. Base the version bump on all of the changes that will be added in this version.
• merge the version PR into main
• check the actions to see when the package is published