@mochabug/adapt-plugin-toolkit
Version:
The API toolkit to facilitate mochabug adapt plugin development
149 lines • 5.09 kB
TypeScript
/**
* Global type definitions for the Mochabug Adapt Plugin system.
* These types define the runtime environment and APIs available to plugins.
*/
/**
* Execution context providing lifecycle management for asynchronous operations.
*/
export interface ExecutionContext {
waitUntil(promise: Promise<any>): void;
passThroughOnException(): void;
abort(reason?: any): void;
}
export interface SocketInfo {
remoteAddress?: string;
localAddress?: string;
}
export interface Socket {
get readable(): ReadableStream;
get writable(): WritableStream;
get closed(): Promise<void>;
get opened(): Promise<SocketInfo>;
get upgraded(): boolean;
get secureTransport(): 'on' | 'off' | 'starttls';
close(): Promise<void>;
startTls(options?: TlsOptions): Socket;
}
export interface TlsOptions {
expectedServerHostname?: string;
}
export interface SocketOptions {
secureTransport?: 'on' | 'off' | 'starttls';
allowHalfOpen: boolean;
highWaterMark?: number | bigint;
}
export interface SocketAddress {
hostname: string;
port: number;
}
export interface Fetcher {
fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
connect(address: SocketAddress | string, options?: SocketOptions): Socket;
}
/**
* Environment represents an interface that holds
* all the common runtime functionality between a plugin - configurator / executor
*
* @interface
*/
export interface Environment {
/**
* assets is a Fetcher that wraps the Web Platform API fetch function.
* It provides access to files inside the assetsDir, as defined in the manifest.json file,
* without requiring authentication.
*
* Note: This is a simple interface to the directory content and is not suitable for serving
* a full-fledged website. For example, it does not attempt to guess the `Content-Type` header.
* You may want to wrap this Fetcher in a plugin that fills in the metadata as required.
*
* A GET request targeting a directory (instead of a file) returns a basic JSON directory
* listing, like:
*
* [
* {"name":"foo","type":"file"},
* {"name":"bar","type":"directory"}
* ]
*
* For file requests, the `Content-Type` will be `application/octet-stream`, while for
* directory listings, it will be `application/json`. Files will have a `Content-Length`
* header, while directories will not.
*
* HEAD requests are optimized to perform a stat() without actually opening the file.
*
* Example Request for fetching an index.html file:
* GET http://./index.html
*
* Example Response:
* HTTP/1.1 200 OK
* Content-Type: application/octet-stream
* Content-Length: 12345
*
* <html>
* ...
* </html>
*
* @type {Fetcher}
*/
assets: Fetcher;
/**
* HTTP Proxy fetcher for secure requests with TLS configuration and dynamic header injection.
* Requests are proxied through the runtime which handles certificate validation, mTLS, and
* template variable substitution.
*
* Service Types:
* - "plugin:name" - System-level services (shared across all vertices)
* - "user:name" - Vertex-level services (per-user configuration)
*
* Required Headers:
* - X-Mochabug-Adapt-Plugin-HttpProxy-Token: Bearer token
* - X-Mochabug-Adapt-Plugin-HttpProxy-Path: "plugin:name" or "user:name"
* - Host: Target host (auto-set by helper methods)
*
* TLS Modes (from service definition):
* - MODE_SERVER_ONLY: Validates server cert against CA bundle
* - MODE_MTLS: Mutual auth requiring client cert + private key
*
* Header Injection:
* - Template syntax: "Bearer %ACCESS_TOKEN%" (Envoy-style)
* - Variables resolved from runtime configuration
* - Injected headers override caller's headers
*
* Error Codes:
* - 400: Invalid header format
* - 401: Invalid token or no permission
* - 412: Service not configured or unavailable
*
* Usage (prefer helper methods):
* ```typescript
* const fetch = api.userHttpProxy("stripe_api");
* const res = await fetch("https://api.stripe.com/v1/charges");
* ```
*
* @type {Fetcher}
*/
httpproxy: Fetcher;
/**
* See the runtime.proto/PluginService for a complete reference
*/
plugin: Fetcher;
}
/**
* The environment available to a executor of a plugin vertex
* See the runtime.proto/ExecutorService for a complete reference
*
* @interface ExecutorEnvironment
*/
export interface ExecutorEnvironment extends Environment {
executor: Fetcher;
}
/**
* The environment available to a configurator of a plugin vertex
* See the runtime.proto/ConfiguratorService for a complete reference
*
* @interface ConfiguratorEnvironment
* @property {Fetcher} configurator - the configurator API
*/
export interface ConfiguratorEnvironment extends Environment {
configurator: Fetcher;
}
//# sourceMappingURL=types.d.ts.map