Functions

What it is

A function is a unit of deployed backend logic (JavaScript/TypeScript, Python, or Ruby) that Volcano builds, packages, and runs on a managed runtime. It is invoked over HTTP, by name/alias, or on a schedule.

How it relates

• Belongs to a project.
• Reads configuration and secrets from variables. By default it receives every project variable; declare a narrower variable scope to give it only the ones it needs.
• Connects to databases and storage in the same project.
• Its visibility (private, authenticated, or public) and schedulers can be declared in the declarative config or managed with the CLI.
• A frontend route can serve a public function under a path of a frontend.
• Can be given an alias so you can invoke it by a friendly name.
• Work that has to run for hours belongs in a durable function instead, which is a separate collection with its own commands.

The CLI discovers functions in the volcano/functions directory, detects the runtime from source file extensions, and uploads a packaged archive.

If a volcano-config.yaml is present, functions deploy also sends the variable_scope and variables declared there for each function it uploads. Functions the manifest does not mention keep their existing scope. The manifest is only read — deploying never writes it back. See variable scope.

Because those declarations come from the manifest, a manifest that is present but cannot be read stops the deploy before anything is uploaded, and the error says what to fix. That includes a ${VAR} reference anywhere in the file whose environment variable is not set in the deploying shell, even in a section unrelated to functions. Deploying past it would upload a function without the scope it declared, giving it every project variable. With no volcano-config.yaml at all there is nothing to declare and deploy runs normally.

Function layout

Each supported file or directory directly under volcano/functions is one function. Names starting with _, such as _lib/, hold shared code that every function archive includes.

TypeScript

The CLI uploads a TypeScript handler as source, and Volcano compiles it to JavaScript during the build, in the cloud and in local mode:

• Types are removed without being checked, so a type error doesn't fail the deploy. Run tsc --noEmit in your own CI to catch type errors.
• .mts compiles to an ES module and .cts to CommonJS. .ts and .tsx are ES modules when the function's package.json sets "type": "module", CommonJS otherwise.
• .tsx compiles JSX with React's automatic runtime, so you don't import React, but react (and a renderer such as react-dom) must be in the function's package.json dependencies. A directory function's tsconfig.json can choose other JSX settings, such as "jsx": "react" with "jsxFactory": "h", or "jsxImportSource": "preact". A single-file function uploads without a tsconfig.json, so put the handler in a directory to change them.
• Imports through paths in a tsconfig.json inside the function's directory resolve. Packages from package.json load from the installed dependencies.
• .ts, .mts and .cts never change what an existing function deploys: hello.js or hello.py beside hello.ts or hello/index.ts, or checkout/index.js, index.mjs, index.cjs, main.py or main.rb beside checkout/index.ts, deploys that file instead. A hello/ directory beside hello.ts deploys the directory.
• .tsx ranks after the other TypeScript: hello.ts beside hello.tsx, or index.ts beside index.tsx in a directory, deploys the .ts file. A hello.ts file also deploys instead of a hello/ directory with only an index.tsx.
• One layout deploys differently than with CLI 0.77.0 and earlier: a hello/ directory with index.mjs or index.cjs beside index.tsx now deploys that JavaScript instead of a hello.ts file, as Git deploy does. Earlier CLIs didn't find that directory.
• Two TypeScript files with one name and no JavaScript, such as hello.ts and hello.mts, stop the deploy until you keep one. Two TypeScript indexes in one directory, such as checkout/index.ts and checkout/index.mts, fail that function's build.
• Declaration files such as types.d.ts aren't functions. A directory needs its handler at its top, such as checkout/index.ts, not checkout/src/index.ts.

See TypeScript for how the build compiles it.

CLI operations

Prefix with cloud (e.g. volcano cloud functions deploy) to target cloud. Without the prefix, function commands always target local development.

Cloud deploys use latest-wins queueing. If the function is already deploying, the new source replaces any older queued deploy and runs next. Delete supersedes queued deploys; later deploys are rejected until deletion finishes.

Visibility

Visibility decides who can invoke a function:

A refused caller gets:

If your app gets 404 for a function you deployed, check its visibility with volcano cloud functions get <name>.

New functions start private. functions deploy says so for each function it creates and prints the command that lets signed-in users in:

  Deployed notes-summary (new, visibility private)

New functions are private: only service keys and schedulers can invoke them.
To let your project's signed-in users call one, run:
  volcano functions update notes-summary --visibility authenticated
Or declare its visibility in volcano-config.yaml and run volcano config deploy

A deploy does not apply the visibility in volcano-config.yaml. When the manifest already declares a level for a new function, the hint points at volcano config deploy instead.

--public is the same as --visibility public. --private is no longer accepted: it used to let signed-in users in, which is authenticated now, so pick the level you mean. A function that a frontend route forwards to has to stay public; functions update lists the routes to delete first.

functions update sets the level of standard functions. For a durable function, declare visibility in volcano-config.yaml and run volcano cloud config deploy.

functions get shows the level, and under "Routed from" every frontend path that forwards to the function:

Visibility: public
Routed from: web /api/session

Examples

volcano deploy deploys the functions together with the project's variables, durable functions, frontends, and configuration. Use functions deploy to deploy only functions.

# Deploy everything, or a single function by name or path
volcano functions deploy --all
volcano functions deploy -f get-notes
volcano functions deploy -f volcano/functions/get-notes.js

# Invoke with a JSON payload; --json prints compact machine output
volcano functions invoke hello --payload '{"name":"Ada"}'
volcano functions invoke hello --json
volcano functions invoke --id 33333333-3333-4333-8333-333333333333

# Let signed-in users invoke a function
volcano functions update notes-summary --visibility authenticated

# Tail build/runtime logs
volcano functions logs hello

# Schedule a function (cron), then disable it
volcano functions schedulers create hello --name refresh-cache --cron "*/5 * * * *"
volcano functions schedulers disable hello --name refresh-cache

# Invoke-by-alias
volcano functions alias set hello 44444444-4444-4444-8444-444444444444
volcano functions invoke hello

schedulers list shows each scheduler's health, how many runs in a row have failed, and the last error of a failing one. A run fails when Volcano cannot invoke the function; an error the function itself returns does not count. To be alerted when a scheduler keeps failing, see notifications.md.