cloud-functions

## Sibling skills (local only) Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`. If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context. **Cross-cutting protocols** (required before code changes or deployments): - Change Safety Protocol: `../cloudbase-platform/references/protocols/change-safety-protocol.md` - Deployment Gate: `../cloudbase-platform/references/protocols/deployment-gate.md` - Sensitive Runtime Data Protection: `../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md` # Cloud Functions Development ## Activation Contract ### Use this first when - The task is to create, update, deploy, inspect, or debug a CloudBase Event Function or HTTP Function that serves application runtime logic. - The request mentions function runtime, function logs, `scf_bootstrap`, function triggers, or function gateway exposure. ### Read before writing code if - You still need to decide between Event Function and HTTP Function. - The task mentions `manageFunctions`, `queryFunctions`, `manageGateway`, or legacy function-tool names. - The task might require `callCloudApi` as a fallback for logs or gateway setup. - An HTTP Function will call CloudBase resources through `@cloudbase/node-sdk` or `@cloudbase/manager-node` -> read `./references/http-function-credentials.md`. HTTP Functions must use explicit credentials; do not rely on the Event Function passwordless runtime path. ### Exception only (do not read by default) - Migrating an **existing** app that already uses classic TCP DB clients (`DATABASE_URL` / Prisma / `mysql2` / `pg` / Redis) → read `./references/vpc-and-tcp-database.md` via `./references.md`. New business CRUD must prefer CloudBase native SDK (`app.database()` / `app.rdb()`) or MCP SQL tools instead of TCP. ### Then also read - Detailed reference routing -> `./references.md` - Auth setup or provider-related backend work -> `../auth-tool-cloudbase/SKILL.md` - CloudBase Integration Center generated WeChat Pay or Official Account functions -> `../cloudbase-wechat-integration/SKILL.md` (official docs: `https://docs.cloudbase.net/integration/introduce.md`) - AI in functions -> `../ai-model-nodejs/SKILL.md` - Long-lived container services or Agent runtimes -> `../cloudrun-development/SKILL.md` - Calling CloudBase official platform APIs from a client or script -> `../http-api-cloudbase/SKILL.md` ### Do NOT use for - CloudRun container services. - Web authentication UI implementation. - Database-schema design or general data-model work. - CloudBase official platform API clients or raw HTTP integrations that only consume platform endpoints. - Creating Integration Center instances through guessed APIs. For WeChat Pay or Official Account generated functions, use `cloudbase-wechat-integration` for the business contract and this skill only for function operations. - **Tasks that the CloudBase JS SDK can handle directly** — simple data reads/writes, leaderboards, file uploads, real-time queries. Reach for the matching SDK surface before writing a function: `db.collection(...).get/add/update` only for confirmed NoSQL collections, and `app.rdb().from(...)` for CloudBase PG tables. Functions add deployment complexity, CORS configuration, and HTTP gateway binding that the SDK eliminates entirely. ### Common mistakes / gotchas - Picking the wrong function type and trying to compensate later. - Confusing official CloudBase API client work with building your own HTTP function. - Mixing Event Function code shape (`exports.main(event, context)`) with HTTP Function code shape (`req` / `res` on port `9000`). - Treating HTTP Access as the implementation model for HTTP Functions. HTTP Access is a gateway configuration for Event Functions, not the HTTP Function runtime model. - Assuming `db.collection("name").add(...)` will create a missing document-database collection automatically. Collection creation is a separate management step. - Forgetting that runtime cannot be changed after creation. - Using cloud functions as the first answer for Web login. - Forgetting that HTTP Functions must ship `scf_bootstrap`, listen on port `9000`, and include dependencies. - Assuming an HTTP Function can use CloudBase SDKs without explicit credentials. The default temporary credential path is not reliable for HTTP Functions and credential rotation can break a running service. Use a CloudBase server API Key or Tencent Cloud key pair for `@cloudbase/node-sdk`; use a Tencent Cloud key pair for `@cloudbase/manager-node`. See `references/http-function-credentials.md`. - Forgetting to configure function security rules after creating an HTTP Function. Default rules reject anonymous callers with `EXCEED_AUTHORITY`. Note: anonymous login is disabled by default for new environments — if the function needs public access without authentication, configure the security rule to allow all callers rather than relying on anonymous login. - Mismatching the `scf_bootstrap` Node.js binary path with the function runtime (e.g. using `/var/lang/node18/bin/node` but setting `runtime: "Nodejs16.13"`). - For Custom Image HTTP Functions: forgetting that TCR, the CloudApp build, and SCF must be in the same region; using `:latest` instead of a unique tag; or confusing the request-driven port-`9000` image model with a long-lived CloudRun container that listens on the injected `PORT`. - Assuming MCP covers the whole image pipeline. `manageFunctions` covers SCF image deploy (Stage B) via `runtime: "CustomImage"` + `imageConfig`, but the CloudApp custom build → TCR push (Stage A) is a raw Tencent Cloud API path — confirm action names and parameters from official docs before any `callCloudApi` fallback. - Making code or configuration changes without first following the Change Safety Protocol (`cloudbase-platform/references/protocols/change-safety-protocol.md`). - Exposing functions publicly or deploying without first completing the checks in `cloudbase-platform/references/protocols/deployment-gate.md`. - **Returning `req.headers`, `process.env`, `event`, or `context` wholesale** — gateways may inject `x-cloudbase-context` (base64 temporary credentials). Never echo that header or dump credential env vars to clients. Follow `../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md`. - **Using a bare layer name (e.g. `common`) across environments.** SCF LayerName is an account-scoped shared namespace: same name → shared version sequence. Create new layers with fixed format `{layerName}_{当前envId}` (e.g. `common_cloud1-d9ghadgak3edf6b36`). Pass the full name as `layerName` — do not invent automatic suffixes. Treat MCP layer `warnings` as soft advisories (operation still succeeds). Details: `./references/operations-and-config.md`. - **Long-running MCP image deployments must complete the full workflow**: When using `manageFunctions` with `deployFunction` for a real `cloud` or `local` deployment, prefer `wait=false` to avoid blocking a single Tool Call for an extended period. If the tool returns a `taskId`, do not end the workflow, report success, or ask the user to wait while the status is `running`. Automatically call `queryFunctions(action="getFunctionDeployStatus", taskId="...")` and continue polling according to the reported progress until the status becomes `succeeded` or `failed`. Only after reaching a reasonable polling limit may you report that the deployment is still in progress; include the `taskId`, current stage, and latest progress. On success, report the image URI or build ID, function status, and Gateway URL. On failure, report the failed stage, error code, request ID, and diagnostic guidance. If the status is `expired`, explain that the local task record exceeded its retention window; the cloud deployment may still be running, so call `getFunctionDetail` to confirm the actual cloud-side status instead of treating it as a failure. ### Minimal checklist - Read [Cloud Functions Execution Checklist](checklist.md) before deployment or runtime changes. - Decide whether the task is Event Function, HTTP Function, or actually CloudRun. - Pick the detailed reference file in [references.md](references.md) before writing implementation code. ## MCP image deployment with polling For real `cloud` or `local` custom-image deployments, prefer: ```json { "action": "deployFunction", "dryRun": false, "confirm": true, "wait": false, "deployConfig": {} } ``` The `wait` field controls whether the current MCP Tool call waits for the complete deployment: - `wait=true`: wait for the manager deployment to reach a terminal result and return it. - `wait=false`: return a `taskId` promptly while the deployment continues in the MCP background. When `wait=false` returns a `taskId`, the deployment workflow is not complete. Automatically call `queryFunctions` with `action="getFunctionDeployStatus"` and that `taskId`; continue while the status is `running`, then stop only at `succeeded` or `failed`. Wait about 5 seconds before the first follow-up query and use the returned progress/`nextActions` to continue without aggressive polling. Do not tell the user to ask again or imply success before a terminal status is returned. An `expired` status means the task exceeded the maximum retention window and was force-terminated locally — the cloud deployment may still be in progress, so confirm the real state with `getFunctionDetail` instead of reporting failure. If a reasonable polling limit is reached, report only that the task is still running, including the `taskId`, current status, current stage, and latest progress. For a terminal result, report the deployment strategy, action, image URI/digest, build ID, function status, Gateway URL, or the failed stage, error code, request ID, and diagnostic next step. ### Personal-tier TCR credentials — never put the password in tool arguments Personal-tier image builds (`imageConfig.imageType="personal"` with `local` / `cloud`) need a TCR push credential. Read it from the MCP process environment, not from tool arguments: - Leave `func.imageConfig.build.registryCredential` **out of the request** when `TCB_TCR_USERNAME` and `TCB_TCR_PASSWORD` are set in the MCP server `env` block — the MCP fills them in automatically, the same way `TENCENTCLOUD_SECRETID` works. - **Never ask the user to paste the password into chat, and never write it into tool arguments.** Anything placed in arguments enters the model context and the tool-call history. - If deployment fails with `CLOUD_REGISTRY_CREDENTIAL_MISSING` or `CLOUD_REGISTRY_CREDENTIAL_INVALID`, instruct the user to add these two variables to the `env` block of their MCP configuration and restart the MCP server. Do not work around it by passing the credential inline. - The username is the Tencent Cloud account UIN and is not itself a secret; it may be passed explicitly if needed. Explicit arguments take precedence per field, so username-in-argument plus password-from-environment is a valid combination. **Know when that environment channel does not exist.** It works only for a local stdio MCP server whose client configuration exposes a custom `env` block. Some GUI clients do not inherit shell exports, and IDE-embedded MCP servers usually inject credentials from a hard-coded allowlist (often only `TENCENTCLOUD_*`), leaving the user no way to set arbitrary variables. Telling those users to "set it in the MCP `env` block" is an instruction they cannot act on. Route them to an enterprise registry (`imageType="enterprise"`, which mints a short-lived TCR token instead of using a fixed password) or to `buildStrategy="image"` with an already-pushed image. ### Enterprise-tier builds require a login state with CAM permission `cloud` / `local` builds against an enterprise registry mint a TCR token through CAM (as does `autoGrant`). Environment-level API Keys and OAuth-issued STS credentials carry no CAM policy, so those calls fail with `UnauthorizedOperation`. The MCP probes the login state before starting a real enterprise build and refuses up front rather than failing midway; treat that error as a routing signal, not a retryable fault: - Sign in with an account-level `TENCENTCLOUD_SECRETID` / `TENCENTCLOUD_SECRETKEY` pair, **or** - Switch to `buildStrategy="image"` and deploy an image that was pushed elsewhere, **or** - Use a personal-tier registry — its static password goes straight to `docker login` without touching CAM, which makes it the one build path that does work for API Key users. ## Writing mode at a glance - If the request is for SDK calls, timers, or event-driven workflows, write an **Event Function** with `exports.main = async (event, context) => {}`. - If the request is for REST APIs, browser-facing endpoints, SSE, or WebSocket, write an **HTTP Function** with `req` / `res` on port `9000`. - For Node.js HTTP Functions, default to the native `http` module unless the user explicitly asks for Express, Koa, NestJS, or another framework. - If the HTTP Function needs custom system libraries or an arbitrary runtime but should still be SCF request-driven and scale to zero, deploy it as a **Custom Image HTTP Function** (`Runtime: CustomImage`) from a TCR image. The container still listens on the fixed port `9000`. See `./references/http-functions-custom-image.md`. This is distinct from a CloudRun container, which listens on the injected `PORT` and runs long-lived. - **有 Dockerfile 的 HTTP 无状态服务可优先考虑 HTTP 云函数，不必上云托管** — a Dockerfile alone does not mean CloudRun. If the service is stateless, request-driven HTTP without long connections / custom runtime / VPC database access, prefer an HTTP Function (or Custom Image HTTP Function) — faster to deploy, cheaper, and no CloudRun environment initialization needed. Route to CloudRun (`../cloudrun-development/SKILL.md`) only for WebSocket/SSE long connections, stable independent processes, custom system dependencies, or VPC DB access. - If the user mentions HTTP access for an existing Event Function, keep the Event Function code shape and add gateway access separately. ## HTTP Function authoring contract Use these rules whenever you are writing the function code itself: - Do not write an HTTP Function as `exports.main(event, context)`. That is the Event Function contract. - Treat the function as a standard web server process that must listen on port `9000`. - With Node.js, prefer `http.createServer((req, res) => { ... })` by default so the runtime contract stays explicit. - With the Node.js native `http` module, do not assume Express-style helpers exist. `req.body`, `req.query`, and `req.params` are not provided for you. - For Node.js HTTP Functions, choose one module system up front and keep it consistent. Default to CommonJS for simple functions (`require(...)`, no `"type": "module"` in `package.json`) unless you explicitly want ES Modules. - If you do choose ES Modules (`"type": "module"` + `import ...`), do not mix in CommonJS-only globals or APIs such as `require(...)`, `module.exports`, or bare `__dirname`. In ESM, derive file paths from `import.meta.url` with `fileURLToPath(...)` only when needed. - With the native `http` module, parse `req.url` yourself with `new URL(...)`, collect the request body from the stream, and only then call `JSON.parse`. Empty bodies should be handled explicitly instead of assuming JSON is always present. - Return responses explicitly with `res.writeHead(...)` and `res.end(...)`, including `Content-Type` such as `application/json; charset=utf-8` for JSON APIs. - **Handle CORS headers**. Browsers block cross-origin requests without proper CORS headers. Default to allowing all origins for simple APIs: - Respond to `OPTIONS` preflight with `200` and CORS headers - Include `Access-Control-Allow-Origin: *` (or specific origin) on all responses - Include `Access-Control-Allow-Methods: GET, POST, OPTIONS` as needed - Include `Access-Control-Allow-Headers: Content-Type` for JSON requests - Keep routing and method handling explicit. Unknown paths should return `404`, and known paths with unsupported methods should normally return `405`. - Keep gateway setup and security-rule changes separate from the runtime code. They affect access, not the HTTP Function programming model. - Do not add HTTP access service configuration when the task is only to create an HTTP Function itself. Gateway paths or custom domains are separate access-layer work; public invocation requirements should be handled through the function security rule workflow (note: anonymous login is disabled by default). - If the HTTP Function calls CloudBase through `@cloudbase/node-sdk` or `@cloudbase/manager-node`, complete the explicit credential gate in `./references/http-function-credentials.md` before deployment. Never hardcode credentials in the function package. - **Never echo sensitive runtime data.** Do not return `req.headers`, `process.env`, or `x-cloudbase-context` in responses. Debug endpoints must use an explicit non-sensitive allowlist. See `../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md`. ## Quick decision table | Question | Choose | | --- | --- | | Triggered by SDK calls or timers? | Event Function | | Needs browser-facing HTTP endpoint? | HTTP Function | | Needs SSE or WebSocket service? | HTTP Function | | Needs custom system libraries / arbitrary runtime, but still SCF request-driven + scale-to-zero? | HTTP Function with `Runtime: CustomImage` (deploy from a TCR image) | | Has a Dockerfile but is a stateless HTTP service (no long connections / custom runtime / VPC DB)? | HTTP Function (or Custom Image HTTP Function) — **not** CloudRun | | Needs long-lived container runtime or custom system environment? | CloudRun | | Only needs HTTP access for an existing Event Function? | Event Function + gateway access | ## How to use this skill (for a coding agent) 1. **Choose the correct runtime model first** - Event Function -> `exports.main(event, context)` - HTTP Function -> web server on port `9000` - If the requirement is really a container service, reroute to CloudRun early 2. **Use the converged MCP entrances** - Reads -> `queryFunctions`, `queryGateway` - Writes -> `manageFunctions`, `manageGateway` - Translate legacy names before acting rather than copying them literally 3. **Write code and deploy, do not stop at local files** - Use `manageFunctions(action="createFunction")` for creation - Use `manageFunctions(action="updateFunctionCode")` for code updates - Use `manageFunctions(action="updateFunctionConfig")` for config updates (timeout, memorySize, envVariables) - For a Custom Image HTTP Function, call `manageFunctions(action="createFunction")` with `func.runtime="CustomImage"` and `imageConfig` (`imageUri` with tag; `registryId` for enterprise TCR); iterate later with `manageFunctions(action="updateFunctionCode")` + `imageConfig`. No `functionRootPath` is needed because the code lives in the image. See `./references/http-functions-custom-image.md`. - Keep `functionRootPath` as the directory that directly contains function folders (e.g., `cloudfunctions/` or `functions/`), NOT the project root and NOT the function subdirectory itself - **Prefer MCP when available** — use `manageFunctions` and `queryFunctions` when those tools are in this session - **CLI fallback when MCP is missing** — if function tools are not loaded (first session / pre-restart), configure MCP for next time, then use `tcb fn deploy` via `../cloudbase-cli/SKILL.md` (see guideline `tooling-fallback.md`). Do not stall waiting for restart. - **Do NOT invent CLI when the runtime has no shell** — if only MCP exists and it works, stay on MCP; if neither works, report the gap - For batch updates (multiple functions), call `manageFunctions(action="updateFunctionConfig")` individually for each function — MCP does not have a `--all` batch parameter like CLI - If an HTTP Function uses `@cloudbase/node-sdk`, prefer a server API Key created with `manageAppAuth(action="createApiKey", keyType="api_key")` and inject it as `CLOUDBASE_APIKEY`; Tencent Cloud `SecretId` / `SecretKey` is also supported - If an HTTP Function uses `@cloudbase/manager-node`, inject Tencent Cloud `SecretId` / `SecretKey`; do not claim that a CloudBase API Key initializes the Manager SDK - Merge credential environment variables with the existing function configuration instead of replacing the whole environment-variable set 4. **Prefer doc-first fallbacks** - If a task falls back to `callCloudApi`, first check the official docs or knowledge-base entry for that action - Confirm the exact action name and parameter contract before calling it - Do not guess raw cloud API payloads from memory 5. **Read the right detailed reference** - Event Function details -> `./references/event-functions.md` - HTTP Function details -> `./references/http-functions.md` - HTTP Function CloudBase SDK credentials -> `./references/http-function-credentials.md` - HTTP Function from a container image (`Runtime: CustomImage`, TCR image pipeline) -> `./references/http-functions-custom-image.md` - Logs, gateway, env vars, layers (`{layerName}_{当前envId}`), and legacy mappings -> `./references/operations-and-config.md`