tcb-ff User Guide
tcb-ffis provided by@cloudbase/functions-framework` and is used to start the cloud function service.
@cloudbase/functions-framework` is a function framework provided by CloudBase for running cloud functions in the cloud, as well as for local development and debugging of cloud functions.
Q: Under what circumstances is it necessary to install
tcb-ff?A: When developing and debugging cloud functions locally, you need to install
tcb-ff.
Installation of tcb-ff
Install globally
# Global Installation of tcb-ff
npm install -g @cloudbase/functions-framework
# Run tcb-ff
tcb-ff
Install in the project
# Local Installation of tcb-ff
npm install @cloudbase/functions-framework
# Run tcb-ff
npx tcb-ff
Using tcb-ff to Start the Cloud Function Service
The following is a common example: it starts the cloud function and monitors file changes (based on nodemon), restarting when files change. This command enables CORS capability, allowing browsers to access the service on the domains *.example.com and www.another.com.
tcb-ff -w --enableCors=true --allowedOrigins=*.example.com,www.another.com
Running tcb-ff in the root directory of the function code starts the cloud function service.
tcb-ff
By default, tcb-ff listens on port 3000. To specify a port, use the --port parameter.
tcb-ff --port=30000
tcb-ff -p=30000
The tcb-fftool supports monitoring local file changes. To enable hot restart mode, use the-w` parameter.
tcb-ff -w
If you access the cloud function service through a browser, you may encounter cross-origin issues. You can enable CORS by using the --enableCors parameter.
tcb-ff --enableCors=true
The --enableCorsparameter enables cross-origin access forOriginset tolocalhost | 127.0.0.1by default. To configure other domains, use the--allowedOrigins` parameter.
tcb-ff --enableCors=true --allowedOrigins=*.example.com,www.another.com
The tcb-fftool supports enablingBasic Authfor authentication. You can specify allowed accounts using the--allowedAccounts` parameter.
tcb-ff --allowedAccounts=abc:123,efg:456
tcb-ff Parameter Description
Description
| Command-line parameter | Environment variable | Default value | Example | Description |
|---|---|---|---|---|
| -w, --watch | / | false | -w | Whether to enable hot restart mode. If enabled, the service will automatically restart when function code files change. |
| --port | PORT | 3000 | --port=3000 | Listening port |
| --extendedContextKey | EXTENDED_CONTEXT_KEY | '' | --extendedContextKey=X-Functions-Extended-Context | Specifies the header field for retrieving the extended context.extendedContext |
| --enableCors | ENABLE_CORS | false | --enableCors=true | Whether to enable CORS. If enabled, you can configure allowed domains. By default, localhost and 127.0.0.1 are allowed. |
| --allowedOrigins | ALLOWED_ORIGINS | localhost,127.0.0.1 | --allowedOrigins="example.com,*.abc.com" | Domains that need to be allowed for CORS. By default, localhost and 127.0.0.1 are allowed. Wildcards are supported, e.g., *.example.com can match www.example.com and auth.example.com. This configuration item takes effect only when enableCors is enabled. |
| --allowedAccounts | ALLOWED_ACCOUNTS | None | --allowedAccounts=abc:123,efg:456 | Allowed accounts. Enables Basic Auth when configured. |
| --gracefulShutdown | GRACEFUL_SHUTDOWN | Enabled when NODE_ENV is not production | --gracefulShutdown=false | Whether to enable graceful shutdown of the service |
| --timeout | TIMEOUT | 0 | --timeout=5000 | Node.js Server timeout, see https://nodejs.org/api/http.html#servertimeout |
| --keepAliveTimeout | KEEP_ALIVE_TIMEOUT | 65000 | --keepAliveTimeout=10000 | Node.js Server keep-alive timeout, see https://nodejs.org/api/http.html#server-keepalivetimeout |
| --captureStack | CAPTURE_STACK | Enabled when NODE_ENV is not production | --captureStack=true | Whether to return the error stack when a request fails |
| --concurrencyLimit | CONCURRENCY_LIMIT | 1000 | --concurrencyLimit=100 | Concurrent request limit. 0 means unlimited |
| --noExit | NO_EXIT | false | --noExit=true | Whether to disable process.exit() to prevent accidental process exit |
| --logHeaderBody | LOG_HEADER_BODY | false | --logHeaderBody=true | Whether to log request headers, request body, response headers, and response body in request logs. If enabled, the body size will be limited to 2KB. |
| --logEventContext | LOG_EVENT_CONTEXT | true | --logEventContext=false | Whether to log the input parameters event and context in request logs |
| --logDirname | LOG_DIRNAME | ./logs | --logDirname=/var/logs | Log file directory |
| --maxLogFileSize | MAX_LOG_FILE_SIZE | 1024 * 1024 * 128(128m) | --maxLogFileSize=2097152 | Maximum size of a single log file in bytes |
| --maxLogFiles | MAX_LOG_FILES | 4 | --maxLogFiles=5 | Maximum number of concurrent log files |
| --interceptOutput | INTERCEPT_OUTPUT | false | --interceptOutput=true | Whether to intercept standard output such as console.log. If intercepted, the content of standard output will be recorded in the log file. |
You can view all parameters by using tcb-ff -h.
$ tcb-ff -h
[@cloudbase/functions-framework@1.6.0][pid:0]
Usage: tcb-ff [options]
Options:
-w, --watch Watch the source file for changes and restart the service. Default is false.
Example: -w
--port, -p Set the port to listen on. Default is 3000.
Example: --port=3000
Environment Variable: PORT
--target Set the target function name. Default is 'main'.
Example: --target=hello
Environment Variable: FUNCTION_TARGET
--source Set the target function filename. Default is 'index.js' (extension differs based on module type).
Example: --source=main.mjs
Environment Variable: FUNCTION_SOURCE
--loadAllFunctions Whether to load all functions in the 'functionsRoot' directory. Default: false.
Example: --loadAllFunctions=true
Environment Variable: LOAD_ALL_FUNCTIONS
--functionsRoot The root directory of the functions. only effective when 'loadAllFunctions' is true.
Example: --functionsRoot=path/to/functionsRoot
Environment Variable: FUNCTIONS_ROOT
--signatureType Set the function format. Currently only 'event' is supported.
Example: --signatureType=event
Environment Variable: SIGNATURE_TYPE
--gracefulShutdown Enable graceful shutdown of the service. Default true when 'NODE_ENV=production' otherwise false.
Example: --gracefulShutdown=false
Environment Variable: GRACEFUL_SHUTDOWN
--timeout Set the Node.js Server timeout. Default is 0.
Example: --timeout=5000
Environment Variable: TIMEOUT
--keepAliveTimeout Set the Node.js Server keep-alive timeout. Default is 65000.
Example: --keepAliveTimeout=10000
Environment Variable: KEEP_ALIVE_TIMEOUT
--captureStack Return error stack when a request fails. Enabled when 'NODE_ENV=production'.
Example: --captureStack=true
Environment Variable: CAPTURE_STACK
--concurrencyLimit Limit the number of concurrent requests. 0 means no limit. Default is 1000.
Example: --concurrencyLimit=100
Environment Variable: CONCURRENCY_LIMIT
--noExit Disable 'process.exit()' to prevent accidental process exit. Default is false.
Example: --noExit=true
Environment Variable: NO_EXIT
--interceptOutput If true, intercept console,process.stdout,process.stderr output. Default: false.
Example: --interceptOutput=true
Environment Variable: INTERCEPT_OUTPUT
--logHeaderBody Log request and response headers and bodies in the request log.
Default is false.
Example: --logHeaderBody=false
Environment Variable: LOG_HEADER_BODY
--logEventContext Log original event and context in the access log. Default is true.
Example: --logEventContext=false
Environment Variable: LOG_EVENT_CONTEXT
--extendedContextKey The key of headers to parse `context.extendedContext`.
`''` means that the feature is turned off.
Default is .
Example: --extendedContextKey=X-Functions-Extended-Context
Environment Variable: EXTENDED_CONTEXT_KEY
--extendedContext The value to parse `context.extendedContext`.
`''` means that the feature is turned off.
This parameter will be ignore when 'extendedContextKey' is specified.
Default is null.
Example: --extendedContext='{"a":1,"b":2}'
Environment Variable: EXTENDED_CONTEXT
--functionsConfigFile Set the multi-functions definition config file. Default is 'cloudbase-functions.json'.
Example: --functionsConfigFile=functions.json
Environment Variable: FUNCTIONS_CONFIG_FILE
--enableCors If true, enable CORS for configured origins. Default is false.
Example: --enableCors=true
Environment Variable: ENABLE_CORS
--allowedOrigins Set the allowed origins for CORS. Default allows localhost,127.0.0.1.
Origins should be domain names without protocol or port.
Wildcard origins are supported. e.g. ['*.example.com'].
Multiple origins should be separated by comma.
Example: --allowedOrigins=*.example.com,www.another.com
Environment Variable: ALLOWED_ORIGINS
--allowedAccounts Set the accounts allowed to access.
If specified, The 'username:password' of request will be verified.
Parameter Format: username1:password1,username1:password1,....
Example: --allowedAccounts=abc:123,efg:456
Access Example:
curl http://username:password@127.0.0.1:3000/
curl -H "Authorization: Basic base64encode(username:password)" http://127.0.0.1:3000/
Environment Variable: ALLOWED_ACCOUNTS
--dry-run Do not start the service, only validate that the code can be loaded. Default is false.
Example: --dry-run