/cloud-functions

name: cloud-functions
description: CloudBase function runtime guide for building, deploying, and debugging your own Event Functions or HTTP Functions. This skill should be used when users need application runtime code on CloudBase, not when they are merely calling CloudBase official platform APIs.
version: 2.26.0
alwaysApply: false

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`

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/index.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 pu