Skip to content

Workbench Technical Specification

1. Objective

Workbench is an interactive console embedded in API method pages. It lets users edit a prepared request, execute it, and inspect the response without leaving the documentation.

It covers docs/tcp/** and docs/client-api/rest/**, uses the existing React application, and sends all TCP operations through a backend bridge because browsers cannot safely access raw TCP.

2. Architecture

  1. A machine-readable manifest describes supported methods.
  2. React loads the schema for the current method.
  3. The user edits and submits a request.
  4. The backend validates authorization, method policy, environment, and payload.
  5. The backend executes the REST or TCP operation.
  6. React renders a normalized response.

Workbench is mounted only on method pages through:

<div id="root_workbench" data-workbench-method="tcp.finance.BalanceIn"></div>

Overview pages without a manifest entry must not display Workbench.

3. Method Manifest

The generated manifest is stored at docs/assets/workbench/manifest.json. Each entry contains a stable ID, page, protocol, command or HTTP method and path, authorization mode, execution mode, parameters, and request example.

Metadata in method front matter is the source of truth. The build generator combines it with parameter tables and request examples. Overrides may be used for nonstandard methods, and CI must verify that the generated manifest is current.

Execution modes are:

  • disabled: display only;
  • read: read-only execution;
  • mutating: execution requiring confirmation;
  • dangerous: hidden or limited to explicitly authorized internal roles.

4. React Interface

The interface must provide:

  • TCP or REST protocol identification;
  • method and command names;
  • environment selection where permitted;
  • TCP host, port, TLS, and token fields;
  • schema-based fields and raw JSON editing;
  • request-example prefilling and reset;
  • client-side validation;
  • explicit confirmation for mutating operations;
  • formatted request and response copying;
  • HTTP status, duration, and correlation ID;
  • distinct validation, authentication, timeout, transport, and upstream errors.

Credentials may be stored in browser storage only after explicit user consent. Anonymous users may inspect examples but cannot execute requests.

5. Backend Bridge

The Node.js bridge runs inside the documentation container on an internal port such as 127.0.0.1:3100. Nginx serves static documentation and proxies /workbench/*, including WebSocket upgrades for /workbench/tcp.

Required routes:

  • GET /workbench/config: public-safe environments and limits;
  • GET /workbench/methods/:methodId: the permitted method schema;
  • POST /workbench/execute: normalized REST execution;
  • WS /workbench/tcp: authenticated TCP connection and command lifecycle.

The browser must never open raw TCP or supply an arbitrary REST URL.

6. REST Flow

The backend authenticates the user, resolves methodId from the manifest, checks permissions and environment policy, validates the payload, builds the upstream request from server-side configuration, executes it, and returns a normalized result.

7. TCP Flow

React opens the Workbench WebSocket and sends connection settings. The backend validates authorization and host policy, opens TCP/TLS, performs the ScaleTrade authentication handshake, validates each command and its confirmation state, serializes the protocol envelope, enforces timeouts and size limits, and returns parsed JSON results.

The exact TCP framing, authentication handshake, request and response envelopes, and correlation ID rules must be confirmed against the ScaleTrade protocol implementation.

8. Security

  • Require authentication for every execution.
  • Disable production execution by default.
  • Maintain a server-side method allowlist.
  • Require confirmation for mutating operations.
  • Restrict dangerous operations to approved roles.
  • Apply rate limits by user, IP, method, and environment.
  • Write an audit record for every attempt.
  • Mask passwords, tokens, secrets, OTP values, and authorization headers.
  • Treat the backend as the authority for permissions, endpoints, commands, and environments.
  • Protect user-provided TCP hosts and ports with an allowlist and private-network policy to prevent SSRF.
  • Enforce connect/read timeouts and request/response size limits.

Recommended rollout: sandbox read-only REST, sandbox read-only TCP, selected sandbox mutations with confirmation, and production only after security, role, audit, and rollback review.

9. Deployment

The runtime image contains Nginx, the Node.js bridge, and a process supervisor. Nginx remains on port 80 and proxies Workbench traffic to the internal bridge. The bridge must not be directly reachable outside the container.

Minimum configuration includes the bridge port, allowed TCP hosts, maximum payload size, connect/read timeouts, and audit enablement.

10. Acceptance Criteria

  • Workbench appears only on supported method pages.
  • Requests are prefilled from the manifest and support both fields and raw JSON.
  • Required fields are validated on both client and server.
  • Unknown method IDs and arbitrary REST URLs are rejected.
  • TCP requests run only through the backend bridge.
  • Transport and upstream errors are distinguishable.
  • Unauthorized users cannot execute requests.
  • Mutating methods require confirmation.
  • HTTP and WebSocket routes work through the documentation host and port.
  • Existing login, profile, contact, bundle, and stylesheet behavior remains intact.

11. Delivery Plan

  1. Prototype the manifest, React component, validation, and mock backend for 5–10 methods.
  2. Add authenticated REST execution, allowlists, audit logging, and rate limits.
  3. Implement the TCP adapter and enable selected read-only sandbox commands.
  4. Cover all TCP and Client REST pages and classify every execution mode.
  5. Add role-based access, metrics, monitoring, and sandbox integration tests.

12. Open Decisions

  • Choose supervisord or an entrypoint process model.
  • Confirm the exact TCP protocol framing and authentication flow.
  • Define roles allowed to execute Server API requests.
  • Decide which authentication modes and environments ship first.
  • Decide whether the first release is strictly read-only.
  • Define tenant isolation, credential storage, audit retention, and TCP host policy.