Server

Requires the server permission.

Runs a local HTTP echo server in the Electron main process (express). Port 0 selects the first available non-privileged port from the OS. Register onRequest before calling start so incoming traffic is routed through your handler.

import type { MainPluginContext } from '@harborclient/sdk';
import { createHttpResponse } from '@harborclient/sdk/runtime-utils';

export function activate(hc: MainPluginContext): void {
  hc.server.onRequest(async (request) => {
    // Legacy: return custom JSON (always HTTP 200), or undefined for the default echo payload.
    if (request.path === '/echo') {
      return { ...request.echo, custom: true };
    }

    // Structured: custom status, headers, body, and delay.
    return createHttpResponse({
      status: 404,
      headers: { 'X-Mock': '1' },
      body: { error: 'not found', path: request.path },
      delayMs: 0
    });
  });
  void hc.server.start({ port: 0 }).then(({ port }) => {
    console.log(`Echo server listening on http://localhost:${port}`);
  });
}

hc.server.onRequest(handler)

Available since v2.0.0

Signature:(handler: (request) => unknown | PluginServerHttpResponse | Promise<...>) => Disposable

Invoked for each incoming HTTP request. The request object includes a default echo payload (args, data, files, form, headers, json, origin, url).

Return either:

• A JSON-serializable value for a legacy body-only response (always HTTP 200 + application/json), or
• A structured PluginServerHttpResponse with kind: 'http-response' (use createHttpResponse(...) from @harborclient/sdk/runtime-utils) for custom status, headers, body, and delayMs.

String body values are sent as raw text (default text/plain unless you set Content-Type). Other bodies use JSON.

Multiple handlers may be registered; each call returns a Disposable that removes only that handler. Handlers run sequentially in registration order. When a handler returns undefined or null, the host keeps the result from the previous handler (starting from the default echo payload).

hc.server.start(options?)

Available since v2.7.0

Signature:(options?: { port?: number }) => Promise<{ port: number }>

Starts listening. Returns the assigned port after the server accepts connections.

hc.server.stop()

Available since v2.7.0

Signature:() => Promise<void>

Stops the echo server owned by this plugin.