跳转到内容

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。

它必须同时服务两类请求:

  1. provider API 调用(baseUrl 的 origin)——可信端点,原样放行(仍带超时);
  2. 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