@cloudbase/manager-node 5.8.9-beta.1 → 5.9.1

package/types/function/index.d.ts

@@ -1,5 +1,5 @@
 import { Environment } from '../environment';
-import { IResponseInfo, ICloudFunction, ICloudFunctionV2, IFunctionLogOptions, ICloudFunctionTrigger, IFunctionInvokeRes, IFunctionLogRes, IFunctionDownloadUrlRes, IFunctionLogDetailOptions, IFunctionLogDetailRes, IFunctionLogOptionsV2, IFunctionLogResV2 } from '../interfaces';
+import { IResponseInfo, ICloudFunction, ICloudFunctionV2, IFunctionLogOptions, ICloudFunctionTrigger, IFunctionInvokeRes, IFunctionLogRes, IFunctionDownloadUrlRes, IFunctionLogDetailOptions, IFunctionLogDetailRes, IFunctionLogOptionsV2, IFunctionLogResV2, IFunctionImageConfig } from '../interfaces';
 import { IFunctionInfo, IFunctionCode as IScfFunctionCode } from './types';
 export interface IFunctionCode {
     func: ICloudFunction;
@@ -124,14 +124,30 @@ export interface IPublishVersionRes extends IResponseInfo {
     Handler: string;
     Timeout: number;
     Runtime: string;
-    Namespace: string;
+    EnvId: string;
+    /** @deprecated 请改用 EnvId */
+    Namespace?: string;
 }
 export interface IListFunctionVersionParams {
     functionName: string;
+    /**
+     * 兼容 SCF 的搜索字段。
+     *
+     * 实测仅接受数字型取值（传其它值报 InvalidParameterValue），但服务端**未按它过滤**：
+     * 传存在的版本号与不存在的数字都返回全量版本列表。
+     */
+    searchKey?: string;
     offset?: number;
+    /** 返回数量，默认 20，最大 100（超过报 Offset must be nonnegative and Limit must be between 0 and 100） */
     limit?: number;
-    order?: string;
-    orderBy?: string;
+    /** 排序方向，仅支持 ASC / DESC（传其它值报 Order must be ASC or DESC） */
+    order?: 'ASC' | 'DESC';
+    /** 排序字段，仅支持 AddTime / ModTime（传其它值报 OrderBy must be AddTime or ModTime） */
+    orderBy?: 'AddTime' | 'ModTime';
+}
+export interface IDeleteFunctionVersionParams {
+    functionName: string;
+    qualifier: string;
 }
 export interface IFunctionVersion {
     Version: string;
@@ -170,6 +186,51 @@ export interface IGetFunctionAlias {
     functionName: string;
     name: string;
 }
+export type IFunctionTrafficType = 'FLOW' | 'HEADERS' | 'UNSUPPORTED';
+/**
+ * 可写的流量策略类型：`UNSUPPORTED` 是查询返回的只读兼容态，不可用于 UpdateAlias
+ */
+export type IUpdatableFunctionTrafficType = 'FLOW' | 'HEADERS';
+export interface IFunctionTrafficRule {
+    Version: string;
+    Weight?: number;
+    Key?: string;
+    Value?: string;
+}
+export interface IFunctionTraffic {
+    Type: IFunctionTrafficType | string;
+    DefaultVersion: string;
+    Rules: IFunctionTrafficRule[];
+}
+/** 传入 UpdateAlias 的可写流量策略（`Type` 不含只读的 `UNSUPPORTED`） */
+export interface IUpdatableFunctionTraffic extends Omit<IFunctionTraffic, 'Type'> {
+    Type: IUpdatableFunctionTrafficType;
+}
+export interface IFunctionBackendVersionWeight {
+    Version: string;
+    Weight: number;
+}
+export interface IFunctionBackendVersionMatch {
+    Version: string;
+    Key: string;
+    Method: string;
+    Expression: string;
+}
+export interface IFunctionBackendRoutingConfig {
+    AdditionalVersionWeights: IFunctionBackendVersionWeight[];
+    AdditionVersionMatches: IFunctionBackendVersionMatch[];
+}
+export type ITrafficRule = IFunctionTrafficRule;
+export type ITraffic = IFunctionTraffic;
+export interface IUpdateFunctionAliasConfigV2 {
+    functionName: string;
+    name?: string;
+    traffic: IUpdatableFunctionTraffic;
+}
+export interface IGetFunctionAliasV2 {
+    functionName: string;
+    name?: string;
+}
 export interface IGetFunctionAliasRes extends IResponseInfo {
     FunctionVersion: string;
     Name: string;
@@ -178,6 +239,14 @@ export interface IGetFunctionAliasRes extends IResponseInfo {
     AddTime: string;
     ModTime: string;
 }
+export interface IGetFunctionAliasResV2 extends IResponseInfo {
+    Name: string;
+    FunctionVersion: string;
+    Traffic: IFunctionTraffic;
+    TrafficEditable: boolean;
+    TrafficCompatibilityReason: string;
+    BackendRoutingConfig: IFunctionBackendRoutingConfig;
+}
 export interface IListFunctionOptions {
     limit?: number;
     offset?: number;
@@ -228,6 +297,13 @@ export interface ILayer {
 }
 /** 企业版 TCR 镜像对 SCF 不可见时的排查指引 */
 export declare const ENTERPRISE_IMAGE_REGION_GUIDANCE = "\u8BF7\u786E\u8BA4 TCR \u4F01\u4E1A\u7248\u5B9E\u4F8B\u5DF2\u5728\u5F53\u524D\u51FD\u6570\u5730\u57DF\u63D0\u4F9B\u53EF\u8BBF\u95EE\u7684\u5B9E\u4F8B\u6216\u590D\u5236\u5B9E\u4F8B\uFF0C\u5E76\u68C0\u67E5 RegistryId\u3001\u955C\u50CF\u5730\u5740\u53CA\u62C9\u53D6\u6743\u9650\u3002";
+/**
+ * 为企业版镜像的典型不可见错误补充排查指引，同时保留原始错误和 requestId。
+ * 仅匹配 SCF 已进入 enterprise 镜像查询阶段的错误，避免给普通网络或鉴权错误误导提示。
+ *
+ * 纯函数：只读入参，**不修改**传进来的错误对象；幂等由 WeakMap 缓存保证。
+ */
+export declare function formatImageDeploymentErrorMessage(error: unknown, imageConfig?: IFunctionImageConfig): string;
 export declare class FunctionService {
     private environment;
     private vpcService;
@@ -244,6 +320,14 @@ export declare class FunctionService {
     updateFunctionIncrementalCode(funcParam: IUpdateFunctionIncrementalCodeParam): Promise<IResponseInfo>;
     /**
      * 创建云函数
+     *
+     * CBF（云开发云函数，`Functions[0].Backend === 'cbf'`）环境差异：
+     * - 默认 runtime 为 `Nodejs24.11`（见 `CBF_ALLOWED_RUNTIMES`）
+     * - 不再注入 `Stamp` / `ClsTopicId` / `ClsLogsetId` 与默认 `Role`
+     * - 不支持定时触发器，内部跳过触发器创建
+     *
+     * 用户显式配置的字段一律原样下发，不支持的字段由服务端报错透传。
+     *
      * @param {ICreateFunctionParam} funcParam
      * @returns {(Promise<IResponseInfo | ICreateFunctionRes>)}
      */
@@ -296,6 +380,13 @@ export declare class FunctionService {
     }): Promise<void>;
     /**
      * 获取云函数详细信息
+     *
+     * CBF（云开发云函数，`Functions[0].Backend === 'cbf'`）环境差异：
+     * - 不再注入 `ShowCode`（CBF 不接受该参数），因此也拿不到函数代码内容，
+     *   需要代码请使用 `downloadFunction`
+     * - 不转发 `codeSecret`：CBF 不支持代码保护，若在此下发会掩盖
+     *   `CreateFunction` / `UpdateFunctionCode` 的真实报错
+     *
      * @param {string} name 云函数名称
      * @returns {Promise<Record<string, string>>}
      */
@@ -365,11 +456,24 @@ export declare class FunctionService {
     getCompleteFunctionLogs(_options: IFunctionLogOptionsV2): Promise<IFunctionLogDetailRes[]>;
     /**
      * 更新云函数配置
+     *
+     * CBF（云开发云函数，`Functions[0].Backend === 'cbf'`）环境差异：
+     * - 不再注入 `ClsTopicId` / `ClsLogsetId`，也不转发 `InstallDependency`
+     * - 环境变量：不传不接受 Key 为空的占位项，清空需提交空数组（传 `envVariables: {}` 即清空）
+     * - 不支持定时触发器：配置里的 `triggers` 会被跳过
+     *
+     * 用户显式配置的字段一律原样下发，不支持的字段由服务端报错透传。
+     *
      * @param {ICloudFunction} func 云函数配置
      * @returns {Promise<IResponseInfo>}
      */
     updateFunctionConfig(func: ICloudFunction): Promise<IResponseInfo>;
     /**
+     * 更新云函数代码
+     *
+     * `UpdateFunctionCode` 只传 `EnvId` 即可（SCF 与 CBF 均实测支持），不再下发冗余的 `Namespace`。
+     *
+     * 注意：CBF（云开发云函数）不支持 `codeSecret`（代码保护），传入后会由服务端报错。
      *
      * @param {IUpdateFunctionCodeParam} funcParam
      * @returns {Promise<IResponseInfo>}
@@ -421,6 +525,11 @@ export declare class FunctionService {
     copyFunction(name: string, newFunctionName: string, targetEnvId?: string, force?: boolean): Promise<IResponseInfo>;
     /**
      * 创建云函数触发器
+     *
+     * CBF（云开发云函数，`Functions[0].Backend === 'cbf'`）环境不支持定时触发器，
+     * 且该接口走 SCF 后端，对 CBF 的函数会返回「未找到指定的函数」这类误导性报错，
+     * 故 CBF 下直接抛错。内部调用点（`createFunction` / `updateFunctionConfig`）会跳过本方法。
+     *
      * @param {string} name 云函数名称
      * @param {ICloudFunctionTrigger[]} triggers 云函数触发器配置
      * @returns {Promise<IResponseInfo>}
@@ -429,6 +538,11 @@ export declare class FunctionService {
     batchCreateTriggers(options: IFunctionBatchOptions): Promise<void>;
     /**
      * 删除云函数触发器
+     *
+     * CBF（云开发云函数，`Functions[0].Backend === 'cbf'`）环境不支持定时触发器，
+     * 且该接口走 SCF 后端，对 CBF 的函数会返回「未找到指定的函数」这类误导性报错，
+     * 故 CBF 下直接抛错。
+     *
      * @param {string} name 云函数名称
      * @param {string} triggerName 云函数触发器名称
      * @returns {Promise<IResponseInfo>}
@@ -498,22 +612,47 @@ export declare class FunctionService {
      */
     listVersionByFunction(listVersionParams: IListFunctionVersionParams): Promise<IFunctionVersionsRes>;
     /**
-     *
+     * 删除函数指定版本
+     * @param {IDeleteFunctionVersionParams} params
+     * @returns {Promise<IResponseInfo>}
+     * @memberof FunctionService
+     */
+    deleteFunctionVersion(params: IDeleteFunctionVersionParams): Promise<IResponseInfo>;
+    /**
+     * 更新函数流量配置（旧版 SCF 协议）
+     * @deprecated 请使用 updateFunctionAliasConfigV2
      * @param {IUpdateFunctionAliasConfig} updateVersionConfigParams
      * @returns {Promise<IResponseInfo>}
      * @memberof FunctionService
      */
     updateFunctionAliasConfig(updateVersionConfigParams: IUpdateFunctionAliasConfig): Promise<IResponseInfo>;
     /**
-     * 查询函数别名详情
+     * 更新函数流量策略（V2，TCB Traffic 协议）
+     * @param {IUpdateFunctionAliasConfigV2} updateVersionConfigParams
+     * @returns {Promise<IResponseInfo>}
+     * @memberof FunctionService
+     */
+    updateFunctionAliasConfigV2(updateVersionConfigParams: IUpdateFunctionAliasConfigV2): Promise<IResponseInfo>;
+    /**
+     * 查询函数别名详情（旧版 SCF 协议）
+     * @deprecated 请使用 getFunctionAliasV2
      * @param {IGetFunctionAlias} params
      * @returns {Promise<IGetFunctionAliasRes>}
      * @memberof FunctionService
      */
     getFunctionAlias(params: IGetFunctionAlias): Promise<IGetFunctionAliasRes>;
     /**
-     * 通过 SCF COS 上传方式（通过 GetTempCosInfo + COS SDK 上传）
-     * 返回 TempCosObjectName 用于创建/更新函数
+     * 查询函数别名详情（V2，TCB Traffic 协议）
+     * @param {IGetFunctionAliasV2} params
+     * @returns {Promise<IGetFunctionAliasResV2>}
+     * @memberof FunctionService
+     */
+    getFunctionAliasV2(params: IGetFunctionAliasV2): Promise<IGetFunctionAliasResV2>;
+    /**
+     * COS 上传方式上传函数代码包，返回 { Key }
+     * - CBF（backend=cbf）：tcb.GetTempCosInfo 获取 PutUrl 直传，Key = 服务端生成的 ObjectKey
+     * - SCF（backend=scf，默认）：scf.GetTempCosInfo + Sign + COS SDK 上传
+     * Key 由 getCodeParams 格式化为 TempCosObjectName 用于创建/更新函数
      */
     uploadFunctionZipToCos(options: IFunctionCode, installDependency: 'TRUE' | 'FALSE'): Promise<{
         Key: string;
@@ -535,8 +674,27 @@ export declare class FunctionService {
         TempCosObjectName: string;
         ZipFile?: undefined;
     }>;
+    /**
+     * CBF 环境的临时代码包上传（tcb.GetTempCosInfo + PutUrl 直传）
+     * - 先压缩再取 PutUrl，避免压缩耗时消耗 PutUrl 约 300 秒的有效期
+     * - PutUrl 过期（403）/ 5xx / 网络错误时重新调用 GetTempCosInfo 刷新地址，不复用旧地址（初始 + 重试共 3 次）
+     * - ObjectKey 由服务端生成，多次调用得到不同上传路径，上传成功后原样返回
+     * @private
+     */
+    private uploadFunctionZipViaPutUrl;
+    /**
+     * 对 PutUrl 发起 HTTP PUT 上传 zip 文件（超时 120 秒，支持 http_proxy 代理）
+     * @private
+     */
+    private putZipFileToUrl;
     private createAccessPath;
     private getTempCosInfo;
+    /**
+     * 创建触发器（带重试）。
+     *
+     * ⚠️ AIP-194：**只重试可重试错误**。旧实现是 catch-all 盲重试 —— 权限不足 / 参数非法这类
+     * **必然失败**的错误也会被重试 3 次，既浪费时间，又把确定性失败伪装成偶发失败、掩盖真实原因。
+     */
     private retryCreateTrigger;
     /**
      * 获取函数配置信息

package/types/utils/cloudbase-request.d.ts

@@ -12,3 +12,25 @@ export declare function cloudBaseRequest(options: {
     method?: string;
     headers?: Record<string, any>;
 }): Promise<any>;
+/**
+ * 数据面（/admin）错误响应结构。
+ *
+ * 来源：`tcblinker/internal/tcberror` 的 `TcbError.ToJSON()`，形如
+ * `{ code, message, requestId }`。无 docs 字段——文档链接由 CLI 侧
+ * `resolveErrorDoc` 按 code + source 生成（见错误码治理方案 §4.6）。
+ */
+export interface IDataPlaneErrorResponse {
+    /** 数据面稳定错误码，见 tcblinker/internal/tcberror（如 INVALID_PARAM / STORAGE_FILE_NONEXIST） */
+    code?: string;
+    message?: string;
+    requestId?: string;
+}
+/**
+ * 校验数据面（/admin）响应，命中错误时抛出带 code 的 CloudBaseError。
+ *
+ * 必须把 `res.code` 落到 `CloudBaseError.code` 并标记 `source: 'runtime'`：
+ * 否则 CLI 侧 `resolveErrorDoc` 拿不到 code → 文档链接哑火，
+ * `resolveExitCode` 也会兜底成 1，灯塔上报退化为 `ERROR`。
+ * 这是「错误码治理方案」D11 的修复点。
+ */
+export declare function assertDataPlaneOk(res: IDataPlaneErrorResponse | null | undefined, action: string): void;