Provider SDK
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/provider-sdk。
DEFAULT_MODEL_REFRESH_ROUTE_ORDER · GuardedFetchOptions · ModelRefreshResult · assertPublicHttpsUrl · createGuardedFetch · createProviderLifecycleFetch · registerModelRefreshRoute
DEFAULT_MODEL_REFRESH_ROUTE_ORDER
注册顺序:与既有各 Provider 保持一致,避免同一路径被别的中间件抢先。
export const DEFAULT_MODEL_REFRESH_ROUTE_ORDER: 25;GuardedFetchOptions
Provider 出网守卫:插件注入给 provider 的唯一 fetch。
它必须同时服务两类请求:
- provider API 调用(
baseUrl的 origin)——可信端点,原样放行(仍带超时); - provider 返回的媒体输出下载(任意 URL)——受控下载:只允许 https、拒绝回环/私网主机、 限制重定向、只接受声明的响应类型、流式字节上限与超时。
第 2 类正是 SSRF 与“超大响应”风险的入口。浏览器提交的 URL 不会走到这里(网关只接受 storageKey)。
各 Provider 的差异收敛成三个选项:allowedContentTypes(图片 / 图片+音频)、
prepareDownloadHeaders(有的 CDN 需要附带凭据)、maxRedirects。
export type GuardedFetchOptions = { baseUrl: string; maxBytes: number; timeoutMs: number; fetchImpl?: typeof globalThis.fetch; apiFetchImpl?: typeof globalThis.fetch; validate?: () => Promise<void>; maxRedirects?: number; allowedContentTypes?: readonly string[]; prepareDownloadHeaders?: (url: URL, headers: Headers) => void;};成员说明:
baseUrl:provider API 的 base URL;其 origin 被视为可信。apiFetchImpl:Dedicated pinned transport for authenticated source API calls; media keeps its existing guard.validate:Check the frozen source before each authenticated upstream call.allowedContentTypes:受控下载允许的响应类型前缀;缺省只允许图片(image/)。prepareDownloadHeaders:受控下载的请求头钩子:由插件决定是否给自己的 CDN 附加凭据。 调用方已带的头会先放进headers;钩子原地修改即可。不要在可信 origin 分支调用它—— 那条路径的请求头由 provider 自己构造。
ModelRefreshResult
刷新结果:成功带模型数量(可选提示),失败带面向管理员的原因。
export type ModelRefreshResult = { ok: true; modelCount: number; message?: string;} | { ok: false; message: string;};assertPublicHttpsUrl
校验一个外部 URL 是否可安全访问:只允许 https、拒绝回环/私网/.local。
上传流程等“不走 guarded fetch、但要自己发请求”的地方用它做同一套校验。
export function assertPublicHttpsUrl(value: string): URL;createGuardedFetch
export function createGuardedFetch(options: GuardedFetchOptions): typeof globalThis.fetch;关联类型:GuardedFetchOptions
createProviderLifecycleFetch
A disposed Provider may retain a receipt handle, but cannot send a new authenticated request.
export function createProviderLifecycleFetch(host: { effect(callback: () => () => void): unknown; }, upstream?: typeof fetch): typeof fetch;registerModelRefreshRoute
注册模型目录刷新路由(POST <path>,需要站点管理员授权)。
只处理该路径的 POST;其它请求返回 false 交下游。鉴权失败统一 401,刷新失败统一 502。
export function registerModelRefreshRoute(ctx: HostExtensionContext, options: RegisterModelRefreshRouteOptions): void;关联类型:HostExtensionContext · RegisterModelRefreshRouteOptions