Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,483 @@
|
||||
/**
|
||||
* @toolctrl/plugin-sdk — Phase 06 Task #21 foundation.
|
||||
*
|
||||
* Type definitions plugin authors `import` against. The package ships
|
||||
* type-only declarations in this foundation step; the AssemblyScript /
|
||||
* Rust toolchain bindings that resolve to actual WASM imports are
|
||||
* deferred to Phase 06 Task #23 (audit + docs).
|
||||
*
|
||||
* Authoring shape:
|
||||
*
|
||||
* import type { HookHandler, PluginContext } from "@toolctrl/plugin-sdk";
|
||||
*
|
||||
* export const handleHello: HookHandler<{ name: string }, { greeting: string }> = (
|
||||
* input,
|
||||
* ctx,
|
||||
* ) => {
|
||||
* ctx.log.info({ name: input.name }, "hello");
|
||||
* return { greeting: `Hello, ${input.name}!` };
|
||||
* };
|
||||
*/
|
||||
|
||||
export const PLUGIN_SDK_PACKAGE_VERSION = "0.0.0";
|
||||
export const PLUGIN_PAYLOAD_ABI_VERSION = 1;
|
||||
export const PLUGIN_PAYLOAD_ABI_IMPORTS = ["env.toolctrl_payload_len", "env.toolctrl_payload_byte"] as const;
|
||||
export const PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION = 1;
|
||||
export const PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME = "plugin-settings-channel";
|
||||
|
||||
/**
|
||||
* Capability names a host exposes to a plugin — mirrors the closed enum
|
||||
* in `@toolctrl/plugin-runtime`. Kept duplicated here so plugin authors
|
||||
* don't need to install the runtime package as a build-time dep.
|
||||
*/
|
||||
export type PluginCapabilityName =
|
||||
| "http.outbound"
|
||||
| "db.read"
|
||||
| "db.write"
|
||||
| "storage.read"
|
||||
| "storage.write"
|
||||
| "log"
|
||||
| "audit"
|
||||
| "tenant.info"
|
||||
| "secret.read";
|
||||
|
||||
/**
|
||||
* Foundation hook names the host can emit. Mirrors the runtime hook
|
||||
* registry so plugin authors can type their handlers without importing
|
||||
* `@toolctrl/plugin-runtime`.
|
||||
*/
|
||||
export type PluginHookName =
|
||||
| "tenant.created"
|
||||
| "user.created"
|
||||
| "entity.created"
|
||||
| "entity.updated"
|
||||
| "entity.deleted"
|
||||
| "workflow.created"
|
||||
| "workflow.updated"
|
||||
| "workflow.deleted"
|
||||
| "workflow.executed"
|
||||
| "workflow.failed";
|
||||
|
||||
export interface PluginHookTenantCreatedPayload {
|
||||
readonly tenantId: string;
|
||||
readonly slug: string;
|
||||
readonly ownerEmail?: string | null;
|
||||
readonly plan?: string | null;
|
||||
readonly createdAt: string;
|
||||
}
|
||||
|
||||
export interface PluginHookUserCreatedPayload {
|
||||
readonly userId: string;
|
||||
readonly tenantId?: string | null;
|
||||
readonly email: string;
|
||||
readonly locale?: string | null;
|
||||
readonly createdAt: string;
|
||||
}
|
||||
|
||||
export interface PluginHookEntityPayload {
|
||||
readonly entityType: string;
|
||||
readonly entityId: string;
|
||||
readonly tenantId: string | null;
|
||||
readonly userId?: string | null;
|
||||
readonly changedFields?: ReadonlyArray<string>;
|
||||
readonly occurredAt: string;
|
||||
}
|
||||
|
||||
export interface PluginHookWorkflowExecutedPayload {
|
||||
readonly tenantId: string;
|
||||
readonly workflowId: string;
|
||||
readonly workflowExecutionId: string;
|
||||
readonly userId?: string | null;
|
||||
readonly type: "manual" | "api" | "stream" | "trigger";
|
||||
readonly status: "success" | "error";
|
||||
readonly durationMs: number;
|
||||
readonly errorCode: string | null;
|
||||
readonly appliesToAllTenants: boolean;
|
||||
readonly occurredAt: string;
|
||||
}
|
||||
|
||||
export interface PluginHookWorkflowFailedPayload extends Omit<PluginHookWorkflowExecutedPayload, "status" | "errorCode"> {
|
||||
readonly status: "error";
|
||||
readonly errorCode: string;
|
||||
}
|
||||
|
||||
export interface PluginHookWorkflowDefinitionPayload {
|
||||
readonly tenantId: string | null;
|
||||
readonly workflowId: string;
|
||||
readonly userId: string | null;
|
||||
readonly status: "draft" | "live" | "archived";
|
||||
readonly appliesToAllTenants: boolean;
|
||||
readonly changedFields?: ReadonlyArray<string>;
|
||||
readonly occurredAt: string;
|
||||
}
|
||||
|
||||
export type PluginHookPayloads = {
|
||||
readonly "tenant.created": PluginHookTenantCreatedPayload;
|
||||
readonly "user.created": PluginHookUserCreatedPayload;
|
||||
readonly "entity.created": PluginHookEntityPayload;
|
||||
readonly "entity.updated": PluginHookEntityPayload;
|
||||
readonly "entity.deleted": PluginHookEntityPayload;
|
||||
readonly "workflow.created": PluginHookWorkflowDefinitionPayload;
|
||||
readonly "workflow.updated": PluginHookWorkflowDefinitionPayload;
|
||||
readonly "workflow.deleted": PluginHookWorkflowDefinitionPayload;
|
||||
readonly "workflow.executed": PluginHookWorkflowExecutedPayload;
|
||||
readonly "workflow.failed": PluginHookWorkflowFailedPayload;
|
||||
};
|
||||
|
||||
/** Subset of pino's logger surface the host exposes via the `log` cap. */
|
||||
export interface PluginLogger {
|
||||
info(fields: Record<string, unknown>, msg: string): void;
|
||||
warn(fields: Record<string, unknown>, msg: string): void;
|
||||
error(fields: Record<string, unknown>, msg: string): void;
|
||||
}
|
||||
|
||||
/** HTTP host binding — gated on the `http.outbound` capability. */
|
||||
export interface PluginHttpClient {
|
||||
fetch(input: { url: string; method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; headers?: Record<string, string>; body?: string }): Promise<{
|
||||
status: number;
|
||||
headers: Record<string, string>;
|
||||
body: string;
|
||||
}>;
|
||||
}
|
||||
|
||||
/** Tenant-scoped KV store — gated on `storage.read` / `storage.write`. */
|
||||
export interface PluginStorage {
|
||||
get(key: string): Promise<string | null>;
|
||||
put(key: string, value: string, opts?: { ttlSeconds?: number }): Promise<void>;
|
||||
}
|
||||
|
||||
/** Audit-event sink — always allowed. */
|
||||
export interface PluginAudit {
|
||||
record(input: { action: string; target?: string; meta?: Record<string, unknown> }): Promise<void>;
|
||||
}
|
||||
|
||||
/** Read-only tenant metadata — always allowed. */
|
||||
export interface PluginTenantInfo {
|
||||
id: string;
|
||||
slug: string;
|
||||
plan: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregate host API surface, partial because each plugin only sees
|
||||
* the bindings whose capabilities it declared in `plugin.toml`.
|
||||
*/
|
||||
export interface HostApi {
|
||||
log: PluginLogger;
|
||||
audit: PluginAudit;
|
||||
tenant?: PluginTenantInfo;
|
||||
http?: PluginHttpClient;
|
||||
storage?: PluginStorage;
|
||||
secret?: { get(key: string): Promise<string | null> };
|
||||
}
|
||||
|
||||
export type PluginSettingValue = null | boolean | number | string | ReadonlyArray<PluginSettingValue> | { readonly [key: string]: PluginSettingValue };
|
||||
|
||||
export type PluginSettingsFrameReadyMessage = {
|
||||
readonly type: "plugin.settings.ready";
|
||||
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
readonly requestId?: string;
|
||||
};
|
||||
|
||||
export type PluginSettingsFrameGetMessage = {
|
||||
readonly type: "plugin.settings.get";
|
||||
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
readonly requestId: string;
|
||||
readonly key: string;
|
||||
};
|
||||
|
||||
export type PluginSettingsFrameSetMessage = {
|
||||
readonly type: "plugin.settings.set";
|
||||
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
readonly requestId: string;
|
||||
readonly key: string;
|
||||
readonly value: PluginSettingValue;
|
||||
};
|
||||
|
||||
export type PluginSettingsFrameMessage = PluginSettingsFrameReadyMessage | PluginSettingsFrameGetMessage | PluginSettingsFrameSetMessage;
|
||||
|
||||
export type PluginSettingsFrameResultMessage =
|
||||
| {
|
||||
readonly type: "plugin.settings.result";
|
||||
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
readonly requestId: string;
|
||||
readonly ok: true;
|
||||
readonly key: string;
|
||||
readonly value: PluginSettingValue;
|
||||
}
|
||||
| {
|
||||
readonly type: "plugin.settings.result";
|
||||
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
readonly requestId: string;
|
||||
readonly ok: false;
|
||||
readonly error: "invalid_payload" | "settings_unavailable" | "settings_update_failed";
|
||||
readonly message: string;
|
||||
};
|
||||
|
||||
export interface PluginSettingsClientMessageTarget {
|
||||
postMessage(message: PluginSettingsFrameMessage, targetOrigin: string): void;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClientMessageEvent {
|
||||
readonly source: unknown;
|
||||
readonly data: unknown;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClientWindow {
|
||||
readonly parent: PluginSettingsClientMessageTarget;
|
||||
addEventListener(type: "message", listener: (event: PluginSettingsClientMessageEvent) => void): void;
|
||||
removeEventListener(type: "message", listener: (event: PluginSettingsClientMessageEvent) => void): void;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClientDocument {
|
||||
querySelector(selector: string): { getAttribute(name: string): string | null } | null;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClientRequestOptions {
|
||||
readonly requestId?: string;
|
||||
readonly timeoutMs?: number;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClientOptions {
|
||||
readonly pluginId: string;
|
||||
readonly channelId?: string;
|
||||
readonly targetOrigin?: string;
|
||||
readonly timeoutMs?: number;
|
||||
readonly requestId?: () => string;
|
||||
readonly window?: PluginSettingsClientWindow;
|
||||
readonly document?: PluginSettingsClientDocument;
|
||||
}
|
||||
|
||||
export interface PluginSettingsClient {
|
||||
readonly pluginId: string;
|
||||
readonly channelId: string;
|
||||
ready(options?: { readonly requestId?: string }): void;
|
||||
get(key: string, options?: PluginSettingsClientRequestOptions): Promise<PluginSettingValue>;
|
||||
set(key: string, value: PluginSettingValue, options?: PluginSettingsClientRequestOptions): Promise<PluginSettingValue>;
|
||||
destroy(): void;
|
||||
}
|
||||
|
||||
type PluginSettingsClientPendingRequest = {
|
||||
readonly key: string;
|
||||
readonly timeout: ReturnType<typeof setTimeout> | null;
|
||||
resolve(value: PluginSettingValue): void;
|
||||
reject(error: Error): void;
|
||||
};
|
||||
|
||||
export class PluginSettingsClientError extends Error {
|
||||
readonly code: PluginSettingsFrameResultMessage extends infer Message
|
||||
? Message extends { readonly ok: false; readonly error: infer Code }
|
||||
? Code
|
||||
: never
|
||||
: never;
|
||||
|
||||
constructor(code: PluginSettingsClientError["code"], message: string) {
|
||||
super(message);
|
||||
this.name = "PluginSettingsClientError";
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
|
||||
export class PluginSettingsClientTimeoutError extends Error {
|
||||
constructor(requestId: string) {
|
||||
super(`Plugin settings request timed out: ${requestId}`);
|
||||
this.name = "PluginSettingsClientTimeoutError";
|
||||
}
|
||||
}
|
||||
|
||||
function getDefaultPluginSettingsWindow(): PluginSettingsClientWindow | undefined {
|
||||
const maybeWindow = (globalThis as { window?: PluginSettingsClientWindow }).window;
|
||||
return maybeWindow?.parent && typeof maybeWindow.addEventListener === "function" && typeof maybeWindow.removeEventListener === "function"
|
||||
? maybeWindow
|
||||
: undefined;
|
||||
}
|
||||
|
||||
function getDefaultPluginSettingsDocument(): PluginSettingsClientDocument | undefined {
|
||||
const maybeDocument = (globalThis as { document?: PluginSettingsClientDocument }).document;
|
||||
return maybeDocument && typeof maybeDocument.querySelector === "function" ? maybeDocument : undefined;
|
||||
}
|
||||
|
||||
function readPluginSettingsChannelId(documentRef: PluginSettingsClientDocument | undefined): string | undefined {
|
||||
return documentRef?.querySelector(`meta[name="${PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME}"]`)?.getAttribute("content") ?? undefined;
|
||||
}
|
||||
|
||||
function isPluginSettingsFrameResultMessage(value: unknown): value is PluginSettingsFrameResultMessage {
|
||||
return typeof value === "object" && value !== null && (value as { type?: unknown }).type === "plugin.settings.result";
|
||||
}
|
||||
|
||||
/**
|
||||
* Build a small settings iframe client around the host postMessage protocol.
|
||||
* Responses are accepted only from `window.parent` and only when protocol
|
||||
* version, plugin id, channel id, and request id match a pending request.
|
||||
*/
|
||||
export function createPluginSettingsClient(options: PluginSettingsClientOptions): PluginSettingsClient {
|
||||
const frameWindow = options.window ?? getDefaultPluginSettingsWindow();
|
||||
if (!frameWindow) {
|
||||
throw new Error("Plugin settings client requires a window with a parent postMessage target");
|
||||
}
|
||||
|
||||
const pluginId = options.pluginId;
|
||||
const channelId = options.channelId ?? readPluginSettingsChannelId(options.document ?? getDefaultPluginSettingsDocument());
|
||||
if (!channelId) {
|
||||
throw new Error("Missing plugin settings channel");
|
||||
}
|
||||
|
||||
const targetOrigin = options.targetOrigin ?? "*";
|
||||
const defaultTimeoutMs = options.timeoutMs ?? 10_000;
|
||||
const nextRequestId =
|
||||
options.requestId ??
|
||||
(() => {
|
||||
let next = 0;
|
||||
return () => `plugin-settings-${++next}`;
|
||||
})();
|
||||
const pending = new Map<string, PluginSettingsClientPendingRequest>();
|
||||
|
||||
const onMessage = (event: PluginSettingsClientMessageEvent) => {
|
||||
if (event.source !== frameWindow.parent || !isPluginSettingsFrameResultMessage(event.data)) {
|
||||
return;
|
||||
}
|
||||
|
||||
const message = event.data;
|
||||
if (message.version !== PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION || message.pluginId !== pluginId || message.channelId !== channelId) {
|
||||
return;
|
||||
}
|
||||
|
||||
const request = pending.get(message.requestId);
|
||||
if (!request) {
|
||||
return;
|
||||
}
|
||||
|
||||
pending.delete(message.requestId);
|
||||
if (request.timeout) {
|
||||
clearTimeout(request.timeout);
|
||||
}
|
||||
|
||||
if (message.ok) {
|
||||
if (message.key !== request.key) {
|
||||
request.reject(new Error(`Plugin settings response key mismatch for request: ${message.requestId}`));
|
||||
return;
|
||||
}
|
||||
request.resolve(message.value);
|
||||
return;
|
||||
}
|
||||
|
||||
request.reject(new PluginSettingsClientError(message.error, message.message));
|
||||
};
|
||||
|
||||
frameWindow.addEventListener("message", onMessage);
|
||||
|
||||
const post = (message: PluginSettingsFrameMessage) => {
|
||||
frameWindow.parent.postMessage(message, targetOrigin);
|
||||
};
|
||||
|
||||
const request = (
|
||||
type: "plugin.settings.get" | "plugin.settings.set",
|
||||
key: string,
|
||||
value: PluginSettingValue | undefined,
|
||||
requestOptions?: PluginSettingsClientRequestOptions
|
||||
) => {
|
||||
const requestId = requestOptions?.requestId ?? nextRequestId();
|
||||
const timeoutMs = requestOptions?.timeoutMs ?? defaultTimeoutMs;
|
||||
|
||||
return new Promise<PluginSettingValue>((resolve, reject) => {
|
||||
const timeout =
|
||||
timeoutMs > 0
|
||||
? setTimeout(() => {
|
||||
pending.delete(requestId);
|
||||
reject(new PluginSettingsClientTimeoutError(requestId));
|
||||
}, timeoutMs)
|
||||
: null;
|
||||
|
||||
pending.set(requestId, { key, timeout, resolve, reject });
|
||||
|
||||
post(
|
||||
type === "plugin.settings.get"
|
||||
? {
|
||||
type,
|
||||
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
|
||||
pluginId,
|
||||
channelId,
|
||||
requestId,
|
||||
key,
|
||||
}
|
||||
: {
|
||||
type,
|
||||
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
|
||||
pluginId,
|
||||
channelId,
|
||||
requestId,
|
||||
key,
|
||||
value: value as PluginSettingValue,
|
||||
}
|
||||
);
|
||||
});
|
||||
};
|
||||
|
||||
return {
|
||||
pluginId,
|
||||
channelId,
|
||||
ready: (readyOptions) =>
|
||||
post({
|
||||
type: "plugin.settings.ready",
|
||||
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
|
||||
pluginId,
|
||||
channelId,
|
||||
requestId: readyOptions?.requestId,
|
||||
}),
|
||||
get: (key, requestOptions) => request("plugin.settings.get", key, undefined, requestOptions),
|
||||
set: (key, value, requestOptions) => request("plugin.settings.set", key, value, requestOptions),
|
||||
destroy: () => {
|
||||
frameWindow.removeEventListener("message", onMessage);
|
||||
for (const [requestId, pendingRequest] of pending) {
|
||||
if (pendingRequest.timeout) {
|
||||
clearTimeout(pendingRequest.timeout);
|
||||
}
|
||||
pendingRequest.reject(new Error(`Plugin settings client destroyed before response: ${requestId}`));
|
||||
}
|
||||
pending.clear();
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-invocation context: bound capabilities + invocation metadata.
|
||||
*/
|
||||
export interface PluginContext {
|
||||
pluginId: string;
|
||||
pluginVersion: string;
|
||||
tenantId: string;
|
||||
hookName: string;
|
||||
capabilities: ReadonlyArray<PluginCapabilityName>;
|
||||
log: PluginLogger;
|
||||
audit: PluginAudit;
|
||||
tenant?: PluginTenantInfo;
|
||||
http?: PluginHttpClient;
|
||||
storage?: PluginStorage;
|
||||
secret?: { get(key: string): Promise<string | null> };
|
||||
}
|
||||
|
||||
/** A hook handler — synchronous or promise-returning. */
|
||||
export interface HookHandler<Input = unknown, Output = unknown> {
|
||||
(input: Input, ctx: PluginContext): Output | Promise<Output>;
|
||||
}
|
||||
|
||||
export type TypedHookHandler<Name extends PluginHookName, Output = unknown> = HookHandler<PluginHookPayloads[Name], Output>;
|
||||
|
||||
/**
|
||||
* Helper to brand a function as a typed hook handler — `defineHook`
|
||||
* exists so authors can rely on inference of `Input` and `Output`
|
||||
* without restating the type at the call site.
|
||||
*/
|
||||
export function defineHook<Input, Output>(handler: HookHandler<Input, Output>): HookHandler<Input, Output> {
|
||||
return handler;
|
||||
}
|
||||
Reference in new issue
Block a user