@cloudbase/app 3.0.3 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/app",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "cloudbase javascript sdk core",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -31,8 +31,24 @@
   "dependencies": {
     "@cloudbase/adapter-interface": "^0.7.1",
     "@cloudbase/adapter-wx_mp": "^1.2.1",
-    "@cloudbase/types": "3.0.3",
-    "@cloudbase/utilities": "3.0.3"
+    "@cloudbase/types": "3.0.5",
+    "@cloudbase/utilities": "3.0.5"
   },
-  "gitHead": "f636691d8dd8edef8c44e788512fa5a1bbbb11af"
+  "peerDependencies": {
+    "@cloudbase/signature-nodejs": ">=1.0.0",
+    "jsonwebtoken": ">=8.0.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudbase/signature-nodejs": {
+      "optional": true
+    },
+    "jsonwebtoken": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
+  },
+  "gitHead": "5f712e638aa0a0f082986a31c6288b18125a3e24"
 }

package/src/index.ts

@@ -101,12 +101,6 @@ class Cloudbase implements ICloudbase {
     ],
   })
   public init(config: ICloudbaseConfig & { lang?: LANGS }): Cloudbase {
-    if (!config.env) {
-      throw new Error(JSON.stringify({
-        code: ERRORS.INVALID_PARAMS,
-        msg: 'env must not be specified',
-      }),)
-    }
     config.endPointMode = config.endPointMode || 'GATEWAY'
 
     // 初始化时若未兼容平台，则使用默认adapter
@@ -114,11 +108,22 @@ class Cloudbase implements ICloudbase {
       this.useDefaultAdapter()
     }
 
-    const reqConfig: IRequestConfig = {
+    // 在判断config.env之前，先处理node环境的配置
+    config = this.dealNodeAdapterConfig(config)
+
+    if (!config.env) {
+      throw new Error(JSON.stringify({
+        code: ERRORS.INVALID_PARAMS,
+        msg: 'env must not be specified',
+      }),)
+    }
+
+    const reqConfig: IRequestConfig & { auth: ICloudbaseConfig['auth'] } = {
       timeout: config.timeout || 5000,
       timeoutMsg: `[${getSdkName()}][REQUEST TIMEOUT] request had been abort since didn't finished within${
         config.timeout / 1000
       }s`,
+      auth: config.auth,
     }
 
     this.requestClient = new Platform.adapter.reqClass(reqConfig)
@@ -148,12 +153,18 @@ class Cloudbase implements ICloudbase {
       _fromApp: app,
       i18n,
       endPointMode: config.endPointMode,
+      auth: config.auth,
     })
     app.requestClient = this.requestClient
     ;(this as any)?.fire?.('cloudbase_init', app)
 
     this.try2InitAuth(app)
 
+    // node环境可以从adapter获取nodeTool的方法
+    if (Platform.adapter?.nodeTool) {
+      Platform.adapter?.nodeTool(app, this.cloudbaseConfig)
+    }
+
     return app
   }
 
@@ -273,6 +284,40 @@ class Cloudbase implements ICloudbase {
       console.log('try2InitAuth error:', error)
     }
   }
+
+  /**
+   * 处理 Node 环境下 adapter 的配置信息
+   * 在 Node 环境中，通过 adapter 自动获取密钥、环境ID、accessKey 等配置，
+   * 减少用户手动传入配置的负担
+   * @param config - 云开发初始化配置对象
+   * @returns 补充了 Node adapter 信息后的配置对象
+   */
+  private dealNodeAdapterConfig(config: ICloudbaseConfig) {
+    // node环境可以从adapter获取默认的secretId和secretKey
+    if (!process.env.IS_BROWSER_BUILD && Platform.adapter?.getSecretInfo) {
+      const secretInfo = Platform.adapter?.getSecretInfo(config)
+      // 将 adapter 提供的密钥信息写入 config.auth
+      config.auth = {
+        ...config.auth,
+        secretId: secretInfo.secretId,
+        secretKey: secretInfo.secretKey,
+        sessionToken: secretInfo.sessionToken,
+        secretType: secretInfo.secretType as any,
+      }
+
+      // node 环境可能可以从上下文获取env，用户未显式指定时自动填充
+      if (!config.env) {
+        config.env = secretInfo.env
+      }
+
+      // node adapter环境能读取到 process.env.CLOUDBASE_APIKEY 时，在没有传入accessKey时，使用 node adapter 提供的 accessKey（process.env.CLOUDBASE_APIKEY）
+      if (!config.accessKey && secretInfo.accessKey) {
+        config.accessKey = secretInfo.accessKey
+      }
+    }
+
+    return config
+  }
 }
 
 // 类型导出
@@ -283,5 +328,16 @@ export const cloudbase: ICloudbase = new Cloudbase()
 
 cloudbase.useAdapters(getWxDefaultAdapter())
 
+// Node 环境下动态引入 adapter，浏览器/小程序打包时 IS_BROWSER_BUILD=true，此分支会被 tree-shaking 移除
+if (!process.env.IS_BROWSER_BUILD) {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    const nodeAdapter = require('./libs/adapter-node').default
+    cloudbase.useAdapters(nodeAdapter)
+  } catch (error) {
+    throw error
+  }
+}
+
 // 默认导出实例
 export default cloudbase

package/src/libs/adapter-node/constants.ts

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/** 统一错误码定义 */
+export const ERROR = {
+  INVALID_PARAM: {
+    code: 'INVALID_PARAM',
+    message: 'invalid param',
+  },
+  SYS_ERR: {
+    code: 'SYS_ERR',
+    message: 'system error',
+  },
+  STORAGE_REQUEST_FAIL: {
+    code: 'STORAGE_REQUEST_FAIL',
+    message: 'storage request fail',
+  },
+  STORAGE_FILE_NONEXIST: {
+    code: 'STORAGE_FILE_NONEXIST',
+    message: 'storage file not exist',
+  },
+  TCB_CLS_UNOPEN: {
+    code: 'TCB_CLS_UNOPEN',
+    message: '需要先开通日志检索功能',
+  },
+  INVALID_CONTEXT: {
+    code: 'INVALID_CONTEXT',
+    message: '无效的context对象，请使用 云函数入口的context参数',
+  },
+}
+
+/** 管理端 API 路径，用于替换 /web 路径（需要密钥签名时） */
+export const ADMIN_PATH = '/admin'
+
+/** 管理端获取客户端凭证 access_token，为管理员权限 */
+export const CLIENT_AUTH_PATH = '/auth/v1/token/clientCredential'
+
+/** 自定义用户 ID 校验规则：4~32 位，允许字母、数字及部分特殊字符 */
+export const checkCustomUserIdRegex = /^[a-zA-Z0-9_\-#@~=*(){}[\]:.,<>+]{4,32}$/
+
+export enum SECRET_TYPE {
+  'SECRET' = 'SECRET',
+  'SESSION_SECRET' = 'SESSION_SECRET',
+}

package/src/libs/adapter-node/context.ts

@@ -0,0 +1,238 @@
+/* eslint-disable import/no-mutable-exports */
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable no-restricted-syntax */
+import { ERROR, SECRET_TYPE } from './constants'
+import { checkIsInScf, getEnv } from './utils'
+import type { IContextParam, ICompleteCloudbaseContext } from './types'
+import { ICloudbaseConfig } from '@cloudbase/types'
+
+/**
+ * 解析并校验云函数入口的 Context 参数
+ * 将下划线命名的字段转为驼峰格式，并解析环境变量
+ *
+ * @param context - 云函数入口传入的 context 对象
+ * @returns 解析后的上下文对象，包含 environment（新架构）或 environ（老架构）
+ * @throws INVALID_CONTEXT - context 不是对象或解析失败时
+ */
+export function parseContext(context: IContextParam) {
+  if (typeof context !== 'object') {
+    throw { ...ERROR.INVALID_CONTEXT, message: 'context 必须为对象类型' }
+  }
+
+  const parseResult: any = {}
+
+  const {
+    memory_limit_in_mb,
+    time_limit_in_ms,
+    request_id,
+    function_version,
+    namespace,
+    function_name,
+
+    environ,
+    environment,
+  } = context
+
+  try {
+    parseResult.memoryLimitInMb = memory_limit_in_mb
+    parseResult.timeLimitIns = time_limit_in_ms
+    parseResult.requestId = request_id
+    parseResult.functionVersion = function_version
+    parseResult.namespace = namespace
+    parseResult.functionName = function_name
+
+    if (environment) {
+      // 新架构：environment 为 JSON 字符串，直接解析
+      parseResult.environment = JSON.parse(environment)
+    } else {
+      // TODO: 考虑移除老架构的兼容逻辑
+      // 老架构：environ 为分号分隔的 key=value 字符串
+      // 存在 bug：value 含特殊字符时可能影响解析
+      const parseEnviron: any = environ?.split(';')
+      const parseEnvironObj: any = {}
+
+      // eslint-disable-next-line @typescript-eslint/no-for-in-array
+      for (const i in parseEnviron) {
+        if (parseEnviron[i].includes('=')) {
+          // 只按第一个 = 切割，保留 value 中的 =
+          const equalIndex = parseEnviron[i].indexOf('=')
+          const key = parseEnviron[i].slice(0, equalIndex)
+          let value: any = parseEnviron[i].slice(equalIndex + 1)
+
+          // value 含逗号时视为数组
+          if (value.indexOf(',') >= 0) {
+            value = value.split(',')
+          }
+          parseEnvironObj[key] = value
+        }
+      }
+
+      parseResult.environ = parseEnvironObj
+    }
+  } catch (_err: any) {
+    throw { ...ERROR.INVALID_CONTEXT }
+  }
+
+  return parseResult
+}
+
+/**
+ * 获取当前云函数内的所有环境变量
+ * 统一从 process.env 和 context 两个来源合并取值
+ *
+ * 取值优先级：context > process.env
+ * 通过 TCB_CONTEXT_KEYS / WX_CONTEXT_KEYS 动态扩展需要读取的环境变量列表
+ *
+ * @param context - 可选，云函数入口的 context 参数
+ * @returns 合并后的完整环境变量上下文
+ */
+export const getCloudbaseContext = (context?: IContextParam): ICompleteCloudbaseContext => {
+  // 云函数环境下校验必要环境变量
+  if (checkIsInScf()) {
+    if (!getEnv('TENCENTCLOUD_REGION')) {
+      console.error('[TCB][ERROR] missing `TENCENTCLOUD_REGION` environment')
+    }
+    if (!getEnv('SCF_NAMESPACE')) {
+      console.error('[TCB][ERROR] missing `SCF_NAMESPACE` environment')
+    }
+  }
+
+  // 第一步：从 process.env 读取基础环境变量
+  const envObj = getEnv()
+  const envFromProcessEnv: any = {
+    TRIGGER_SRC: envObj.TRIGGER_SRC,
+    _SCF_TCB_LOG: envObj._SCF_TCB_LOG,
+    SCF_NAMESPACE: envObj.SCF_NAMESPACE,
+    TENCENTCLOUD_RUNENV: envObj.TENCENTCLOUD_RUNENV,
+    TENCENTCLOUD_SECRETID: envObj.TENCENTCLOUD_SECRETID,
+    TENCENTCLOUD_SECRETKEY: envObj.TENCENTCLOUD_SECRETKEY,
+    TENCENTCLOUD_SESSIONTOKEN: envObj.TENCENTCLOUD_SESSIONTOKEN,
+    WX_CONTEXT_KEYS: envObj.WX_CONTEXT_KEYS,
+    WX_TRIGGER_API_TOKEN_V0: envObj.WX_TRIGGER_API_TOKEN_V0,
+    WX_CLIENTIP: envObj.WX_CLIENTIP,
+    WX_CLIENTIPV6: envObj.WX_CLIENTIPV6,
+    TCB_CONTEXT_KEYS: envObj.TCB_CONTEXT_KEYS,
+    TCB_CONTEXT_CNFG: envObj.TCB_CONTEXT_CNFG,
+    LOGINTYPE: envObj.LOGINTYPE,
+  }
+
+  // 第二步：从 context 中解析环境变量
+  let envFromContext: any = {}
+  if (context) {
+    const { environment, environ } = parseContext(context)
+    envFromContext = environment || environ || {}
+  }
+
+  // 第三步：根据 CONTEXT_KEYS 动态扩展变量列表（优先取 context 中的值）
+  const tcbContextKeys = envFromContext.TCB_CONTEXT_KEYS || envObj.TCB_CONTEXT_KEYS
+  const wxContextKeys = envFromContext.WX_CONTEXT_KEYS || envObj.WX_CONTEXT_KEYS
+
+  if (tcbContextKeys) {
+    try {
+      const tcbKeysList = tcbContextKeys.split(',')
+      for (const item of tcbKeysList) {
+        envFromProcessEnv[item] = envFromContext[item] || getEnv(item)
+      }
+    } catch (_e) {
+      //
+    }
+  }
+
+  if (wxContextKeys) {
+    try {
+      const wxKeysList = wxContextKeys.split(',')
+      for (const item of wxKeysList) {
+        envFromProcessEnv[item] = envFromContext[item] || getEnv(item)
+      }
+    } catch (_e) {
+      //
+    }
+  }
+
+  // 第四步：合并所有来源，context 的值覆盖 process.env，过滤 undefined
+  const allContext = { ...envFromProcessEnv, ...envFromContext }
+
+  const finalContext: any = {}
+  for (const key in allContext) {
+    if (allContext[key] !== undefined) {
+      finalContext[key] = allContext[key]
+    }
+  }
+
+  return finalContext
+}
+
+/** 缓存 extendedContext，供其他模块读取（如 tool.ts 中获取 userId） */
+export let INIT_CONFIG: ICloudbaseConfig = {} as unknown as ICloudbaseConfig
+
+/**
+ * 从环境变量中获取腾讯云临时密钥信息
+ * 用于 API 请求签名
+ */
+export const getSecretInfo = (config?: ICloudbaseConfig) => {
+  INIT_CONFIG = JSON.parse(JSON.stringify(config || {}))
+
+  const { TCB_ENV, SCF_NAMESPACE } = getCloudbaseContext()
+
+  let env = config?.env || TCB_ENV || SCF_NAMESPACE || ''
+  const defaultInfo = {
+    env,
+    secretId: '',
+    secretKey: '',
+    sessionToken: '',
+    accessKey: '',
+    secretType: '',
+  }
+
+  if (config?.accessKey) {
+    return defaultInfo
+  }
+
+  if (config?.auth?.secretId && config?.auth?.secretKey) {
+    return {
+      ...defaultInfo,
+      secretId: config.auth.secretId,
+      secretKey: config.auth.secretKey,
+      secretType: SECRET_TYPE.SECRET,
+    }
+  }
+
+  const secretEnv = getEnv()
+  const { TENCENTCLOUD_SECRETID } = secretEnv
+  const { TENCENTCLOUD_SECRETKEY } = secretEnv
+  const { TENCENTCLOUD_SESSIONTOKEN } = secretEnv
+  const { CLOUDBASE_APIKEY } = secretEnv
+
+  if (CLOUDBASE_APIKEY) {
+    return {
+      ...defaultInfo,
+      accessKey: CLOUDBASE_APIKEY,
+    }
+  }
+
+  if (TENCENTCLOUD_SECRETID && TENCENTCLOUD_SECRETKEY) {
+    return {
+      ...defaultInfo,
+      secretId: TENCENTCLOUD_SECRETID,
+      secretKey: TENCENTCLOUD_SECRETKEY,
+      sessionToken: TENCENTCLOUD_SESSIONTOKEN || '',
+      secretType: SECRET_TYPE.SESSION_SECRET,
+    }
+  }
+
+  if (config?.context?.extendedContext) {
+    const { extendedContext } = config.context
+    if (!env) {
+      env = extendedContext.envId || ''
+    }
+
+    return {
+      ...defaultInfo,
+      secretId: extendedContext?.tmpSecret?.secretId || '',
+      secretKey: extendedContext?.tmpSecret?.secretKey || '',
+      sessionToken: extendedContext?.tmpSecret?.token || '',
+    }
+  }
+
+  return { ...defaultInfo }
+}

package/src/libs/adapter-node/index.ts

@@ -0,0 +1,166 @@
+/* eslint-disable prefer-destructuring */
+/* eslint-disable @typescript-eslint/naming-convention */
+import {
+  SDKAdapterInterface,
+  StorageInterface,
+  StorageType,
+  WebSocketContructor as WebSocketConstructor,
+} from '@cloudbase/adapter-interface'
+
+import { NodeRequest } from './request'
+import { nodeTool } from './tool'
+import { getSecretInfo } from './context'
+import { parseQueryString } from './utils'
+import { ICloudbaseConfig } from '@cloudbase/types'
+
+// ws 延迟加载，避免非 Node 环境打包时引入
+let _WS: any = null
+function getWS() {
+  if (!_WS) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+      _WS = require('ws')
+    } catch (e) {
+      throw new Error('缺少依赖 ws，请执行以下命令安装：\n\n'
+        + '  npm install ws\n\n'
+        + '该依赖用于 Node 环境下的 WebSocket 连接。',)
+    }
+  }
+  return _WS
+}
+
+// Re-export for external consumers
+export { NodeRequest } from './request'
+export { parseQueryString, createWebStreamFromNodeReadableStream } from './utils'
+export type {
+  ICreateTicketOpts,
+  IGetUserInfoResult,
+  IGetEndUserInfoResult,
+  IUserInfoQuery,
+  IContextParam,
+  ICompleteCloudbaseContext,
+} from './types'
+
+/**
+ * 环境匹配检测：判断当前运行环境是否为 Node.js
+ * SDK 通过此方法决定是否使用当前 adapter
+ */
+function isMatch(): boolean {
+  // eslint-disable-next-line eqeqeq
+  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null
+}
+
+/**
+ * 基于 Map 的内存存储实现
+ * Node.js 环境下无浏览器 Storage API，使用内存 Map 模拟
+ */
+const storage: StorageInterface = (() => {
+  const db = new Map()
+  return {
+    mode: 'sync',
+    setItem(key, value) {
+      db.set(key, value)
+    },
+    getItem(key) {
+      return db.get(key)
+    },
+    removeItem(key) {
+      db.delete(key)
+    },
+    clear() {
+      db.clear()
+    },
+  }
+})()
+
+/**
+ * 生成 Node.js 环境的 SDK Adapter
+ * 组装请求类、存储、WebSocket、认证等能力
+ *
+ * @param options - 配置项，包含 EventBus（用于验证码回调）
+ * @returns SDK Adapter 实例
+ */
+function genAdapter(options: any) {
+  const adapter: SDKAdapterInterface & {
+    getSecretInfo: (config?: ICloudbaseConfig) => {
+      env: string
+      secretId: string
+      secretKey: string
+      sessionToken: string
+      accessKey: string
+      secretType: string
+    }
+    nodeTool: (app: any, config: ICloudbaseConfig) => void
+  } = {
+    nodeTool,
+    getSecretInfo,
+    root: { globalThis: {} },
+    reqClass: NodeRequest,
+    wsClass: getWS() as WebSocketConstructor,
+    sessionStorage: storage,
+    localStorage: storage,
+    primaryStorage: StorageType.session,
+    captchaOptions: {
+      /**
+       * 验证码处理回调
+       * 解析 data: URI 中的验证码参数，通过 EventBus 通知业务层
+       * 等待业务层返回验证结果后 resolve
+       */
+      openURIWithCallback: (_url: string) => {
+        const { EventBus } = options
+        let queryObj: Record<string, string | string[]> = {}
+        let url = _url
+
+        // 从 data: URI 中提取查询参数
+        const matched = _url.match(/^(data:.*?)(\?[^#\s]*)?$/)
+        if (matched) {
+          url = matched[1]
+          const search = matched[2]
+          if (search) {
+            queryObj = parseQueryString(search)
+          }
+        }
+
+        const { token, ...restQueryObj } = queryObj
+
+        // data: 协议但无 token，视为无效验证码数据
+        if (/^data:/.test(url) && !token) {
+          return Promise.reject({
+            error: 'invalid_argument',
+            error_description: `invalie captcha data: ${_url}`,
+          })
+        }
+        if (!token) {
+          return Promise.reject({
+            error: 'unimplemented',
+            error_description: 'need to impl captcha data',
+          })
+        }
+
+        return new Promise((resolve) => {
+          // 通知业务层展示验证码
+          EventBus.$emit('CAPTCHA_DATA_CHANGE', {
+            ...restQueryObj,
+            token,
+            url,
+          })
+
+          // 等待业务层返回验证结果
+          EventBus.$once('RESOLVE_CAPTCHA_DATA', (res: { captcha_token: string; expires_in: number }) => {
+            resolve(res)
+          })
+        })
+      },
+    },
+  }
+  return adapter
+}
+
+/** Node.js Adapter 入口导出 */
+const adapter = {
+  genAdapter,
+  isMatch,
+  runtime: 'node-adapter',
+}
+
+export default adapter

package/src/libs/adapter-node/metadata.ts

@@ -0,0 +1,69 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+// 注意：改地址已经不是一定可以访问的了
+export const kMetadataBaseUrl = 'http://metadata.tencentyun.com'
+
+export const kAppIdPath = 'meta-data/app-id'
+export const kSecurityCredentialsPath = 'meta-data/cam/security-credentials'
+
+export enum kMetadataVersions {
+  'v20170919' = '2017-09-19',
+  'v1.0' = '1.0',
+  'latest' = 'latest',
+}
+
+export function isAppId(appIdStr: string) {
+  return /^[1-9][0-9]{4,64}$/gim.test(appIdStr)
+}
+
+export async function lookup(path: string, options: { timeout?: number } = {}): Promise<string> {
+  const url = `${kMetadataBaseUrl}/${kMetadataVersions.latest}/${path}`
+
+  const controller = new AbortController()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  if (options.timeout) {
+    timer = setTimeout(() => controller.abort(), options.timeout)
+  }
+
+  try {
+    const resp = await fetch(url, { signal: controller.signal })
+    if (resp.status === 200) {
+      return await resp.text()
+    }
+    throw new Error(`[ERROR] GET ${url} status: ${resp.status}`)
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+const metadataCache: { appId: string | undefined } = {
+  appId: undefined,
+}
+/**
+ * lookupAppId - 该方法主要用于判断是否在云上环境
+ * @returns
+ */
+export async function lookupAppId(): Promise<string> {
+  if (metadataCache.appId === undefined) {
+    try {
+      // 只有首次会请求且要求快速返回，超时时间很短，DNS无法解析将会超时返回
+      // 在云环境中，这个时间通常在 10ms 内，部分耗时长（30+ms）的情况是 DNS 解析耗时长（27+ms）
+      const appId = await lookup(kAppIdPath, { timeout: 30 })
+      if (isAppId(appId)) {
+        metadataCache.appId = appId
+      } else {
+        metadataCache.appId = ''
+      }
+    } catch (_e) {
+      // ignore
+    }
+  }
+  return metadataCache.appId || ''
+}
+
+export async function lookupCredentials(ruleName: string): Promise<string> {
+  // `${kMetadataBaseUrl}/meta-data/cam/security-credentials/TCB_QcsRole`
+  // 这里设置了一个较短的超时时间，因为这个请求是在云环境中发起的，通常会很快返回
+  return await lookup(`${kSecurityCredentialsPath}/${ruleName}`, {
+    timeout: 200,
+  })
+}