跳转到内容

后端 web-contracts-src-extension-host-http

本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。

返回接口索引

APPLICATION_EXTENSION_HANDLER_PURPOSES · APPLICATION_EXTENSION_HTTP_METHODS · ApplicationExtensionHandlerPurpose · ApplicationExtensionHttpHandler · ApplicationExtensionHttpMethod · ApplicationExtensionHttpRegistration · ApplicationExtensionHttpRequest · ApplicationExtensionHttpResponse · ApplicationExtensionPublicRouteMapping · ApplicationExtensionRawRequest · ApplicationExtensionRawResponse · ApplicationExtensionStreamBudget · DEFAULT_PLUGIN_STREAM_BUDGET · isApplicationExtensionHandlerPurpose · isApplicationExtensionHttpMethod · validatePublicRouteMapping

APPLICATION_EXTENSION_HANDLER_PURPOSES

handler 用途:区分新工作入口与在途工作控制,使 draining 只拒绝新工作。

  • read:只读状态/快照;
  • auth-transaction:授权事务(start/complete/cancel/disconnect);
  • new-work:受理新的生成/提交工作;
  • work-control:查询、取消、回执等对已受理工作的控制(draining 仍可用)。
export const APPLICATION_EXTENSION_HANDLER_PURPOSES: readonly ["read", "auth-transaction", "new-work", "work-control"];

APPLICATION_EXTENSION_HTTP_METHODS

export const APPLICATION_EXTENSION_HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];

ApplicationExtensionHandlerPurpose

export type ApplicationExtensionHandlerPurpose = (typeof APPLICATION_EXTENSION_HANDLER_PURPOSES)[number];

关联类型:APPLICATION_EXTENSION_HANDLER_PURPOSES

ApplicationExtensionHttpHandler

一个受控 HTTP handler:插件在 backend 入口实现,宿主在 method/route/认证/预算校验后调用。

返回 true 表示已处理并结束响应;false 表示未匹配(不应发生,宿主已按 registration 分派)。

export type ApplicationExtensionHttpHandler = (req: ApplicationExtensionHttpRequest, res: ApplicationExtensionHttpResponse) => Promise<void>;

关联类型:ApplicationExtensionHttpRequest · ApplicationExtensionHttpResponse

ApplicationExtensionHttpMethod

export type ApplicationExtensionHttpMethod = (typeof APPLICATION_EXTENSION_HTTP_METHODS)[number];

关联类型:APPLICATION_EXTENSION_HTTP_METHODS

ApplicationExtensionHttpRegistration

一次 HTTP handler 注册(纯描述;可执行 handler 由后端入口契约提供)。

export type ApplicationExtensionHttpRegistration = {
route: string;
method: ApplicationExtensionHttpMethod;
auth: ApplicationExtensionAuthLevel;
purpose: ApplicationExtensionHandlerPurpose;
stream?: boolean;
};

关联类型:ApplicationExtensionHttpMethod · ApplicationExtensionAuthLevel · ApplicationExtensionHandlerPurpose

成员说明:

  • stream:声明为流式 handler(SSE 等)时启用流预算。

ApplicationExtensionHttpRequest

抽象 HTTP 请求/响应 facade(不依赖 Node)。

后端入口契约提供把 IncomingMessage/ServerResponse 适配到本形状的实现;纯契约层不 import node:http。这允许插件在自己的 backend 入口持有 Node 类型,而公共 DTO 保持浏览器安全。

export type ApplicationExtensionHttpRequest = {
method: ApplicationExtensionHttpMethod;
url: string;
headers: Record<string, string | string[] | undefined>;
readBody: (maxBytes: number) => Promise<Uint8Array>;
signal: AbortSignal;
principal?: PrincipalContext;
accessControl?: boolean;
dataScope?: DataScope;
sessionId?: string;
auditActor?: string;
};

关联类型:ApplicationExtensionHttpMethod · PrincipalContext · DataScope

成员说明:

  • url:相对路径 + query(同源)。
  • readBody:读取请求体(有上限;超出抛错)。
  • signal:请求取消信号(连接断开/超时);执行层必须据此中止未完成工作。
  • principal:可信身份(由宿主在进入插件前建立)。
  • sessionId:会话绑定(存在时)。
  • auditActor:审计 actor(不参与授权)。

ApplicationExtensionHttpResponse

export type ApplicationExtensionHttpResponse = {
setHeader: (name: string, value: string | readonly string[]) => void;
writeHead: (status: number) => void;
write: (chunk: string | Uint8Array) => void;
end: (chunk?: string | Uint8Array) => void;
readonly writableEnded: boolean;
onClose: (listener: () => void) => void;
};

成员说明:

  • write:写入并立即 flush(流式)。
  • end:结束并 flush。
  • writableEnded:是否已结束/连接已关闭。
  • onClose:连接关闭回调(断开清理)。

ApplicationExtensionPublicRouteMapping

可信清单中声明的固定公开路径映射(如 /api/oauth-agent/* → 某 registration)。

export type ApplicationExtensionPublicRouteMapping = {
extensionId: string;
publicPath: string;
route: string;
methods: readonly ApplicationExtensionHttpMethod[];
};

关联类型:ApplicationExtensionHttpMethod

成员说明:

  • extensionId:拥有该映射的插件(宿主据此定位 registration owner)。
  • publicPath:公开路径前缀,必须以 / 开头且不含模板变量。
  • route:目标 registration 的 route(相对宿主 base path)。

ApplicationExtensionRawRequest

结构化的原始 HTTP 请求(不 import node:http,保持 contracts 浏览器安全)。

真实的 Node IncomingMessage 在结构上满足本形状;后端入口契约据此声明“原始 req/res 扩展点” (design D4 允许“原始 req/res 访问或等价 facade”),插件可在 backend 入口按需 cast 回 Node 类型。

export type ApplicationExtensionRawRequest = {
readonly method?: string;
readonly url?: string;
readonly headers: Record<string, string | string[] | undefined>;
on(event: string, listener: (...args: never[]) => void): unknown;
destroy(error?: Error): unknown;
};

ApplicationExtensionRawResponse

结构化的原始 HTTP 响应(同上:Node ServerResponse 结构兼容)。

export type ApplicationExtensionRawResponse = {
statusCode: number;
setHeader(name: string, value: string | readonly string[]): unknown;
writeHead(statusCode: number, headers?: Record<string, string | readonly string[]>): unknown;
write(chunk: unknown): unknown;
end(chunk?: unknown): unknown;
flushHeaders?(): void;
readonly writableEnded: boolean;
readonly headersSent?: boolean;
on(event: string, listener: (...args: never[]) => void): unknown;
};

ApplicationExtensionStreamBudget

流式响应预算(仅对声明 stream 的 handler 生效)。

export type ApplicationExtensionStreamBudget = {
heartbeatMs: number;
deadlineMs: number;
maxEvents: number;
maxBytes: number;
};

成员说明:

  • heartbeatMs:心跳间隔(毫秒)。
  • deadlineMs:执行 deadline(毫秒);正数到达后产生实际取消信号,0 表示不限时。
  • maxEvents:单连接最大事件数。
  • maxBytes:单连接最大累计字节。

DEFAULT_PLUGIN_STREAM_BUDGET

export const DEFAULT_PLUGIN_STREAM_BUDGET: ApplicationExtensionStreamBudget;

关联类型:ApplicationExtensionStreamBudget

成员说明:

  • heartbeatMs:心跳间隔(毫秒)。
  • deadlineMs:执行 deadline(毫秒);正数到达后产生实际取消信号,0 表示不限时。
  • maxEvents:单连接最大事件数。
  • maxBytes:单连接最大累计字节。

isApplicationExtensionHandlerPurpose

判定一个字符串是否为受支持的 handler 用途。

export function isApplicationExtensionHandlerPurpose(value: unknown): value is ApplicationExtensionHandlerPurpose;

关联类型:ApplicationExtensionHandlerPurpose

isApplicationExtensionHttpMethod

export function isApplicationExtensionHttpMethod(value: unknown): value is ApplicationExtensionHttpMethod;

关联类型:ApplicationExtensionHttpMethod

validatePublicRouteMapping

校验公开路径映射(纯数据;可信清单构建时调用)。

export function validatePublicRouteMapping(value: unknown): { ok: true; value: ApplicationExtensionPublicRouteMapping; } | { ok: false; code: string; message: string; };

关联类型:ApplicationExtensionPublicRouteMapping