后端 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; };