Recipes

A recipe is a small function, written as JSON. It takes parameters, runs its steps in order on the server, and returns a result.

The editor

Every server has a node editor: open the server's page and choose Recipes. Add steps as nodes, connect them with wires, try them out in the side panel, and save. Press ? Controls in the editor for the mouse and keyboard shortcuts.

The coloured wires carry data. Without flow nodes, the dotted line with the arrows shows the order the steps run in, which follows from how you've wired them. With flow nodes, you decide the order yourself. Press Run and the nodes light up in the order they ran, each showing its result.

Recipes belong to one server. They're stored in its private .internal/recipes/ folder, which visitors can never reach. They count towards your storage, and a zip deploy with Replace leaves them alone.

The format

Behind the nodes, a recipe is a JSON file. You can also write one by hand: use Import JSON in the editor, or upload it as .internal/recipes/receipt_line.json with the API or in a zip, where the file name is the recipe's name.

{
  "name": "One line of a receipt",
  "parameters": {
    "item": "string",
    "price": "numeric[0..inf]",
    "quantity": { "type": "integer[1..99]", "default": 1 }
  },
  "recipe": [
    { "action": "multiply", "values": ["$price", "$quantity"], "result": "total" },
    { "action": "format", "format": "%(item): %(total:.2f) €" }
  ],
  "result": "$0"
}

Other keys are ignored, so you can leave notes on a step, like "note": "work out the discount".

Recipes can't read files, reach the network or read the clock. To remember something between runs, use storage.

Flow and conditions

To make something happen only in some cases, or to use storage, add flow nodes. They have arrow-shaped pins, and thick flow wires between them decide what runs next. Wire the Start pin on the Inputs node to the first one.

All other nodes are data nodes: they don't have a place in the flow, and are worked out when a flow node needs their result, once per run. A data node nobody asks for doesn't run at all. When a path runs out of flow wires, the recipe ends with the Return node's result.

In JSON, a flow recipe has "nodes" and "start" instead of "recipe". Older recipes keep working as they are.

{
  "parameters": { "score": "numeric[0..100]" },
  "start": "check",
  "nodes": {
    "enough": { "action": "greater_equal", "values": ["$score", 50], "result": "is_enough" },
    "check":  { "action": "branch", "condition": "$is_enough", "then": "pass", "else": "failed" },
    "pass":   { "action": "return", "value": "passed" },
    "failed": { "action": "return", "value": "failed" }
  }
}

Flow wires can't form a loop, so a recipe always finishes. A value from a flow node only exists once that node has run: using one from a branch that wasn't taken is an error.

Storage

Each site has its own storage: named values that are still there on the next run, for every visitor. These are all flow nodes.

A visitor counter. Use it from a page with %{ visits() }%, which then runs again on every view:

{
  "start": "count",
  "nodes": {
    "count": { "action": "storage_increment", "values": ["visits"], "result": "total" },
    "show":  { "action": "format", "format": "Visitor number %(total)", "result": "text" }
  },
  "result": "$text"
}

• All or nothing. Changes are only saved if the whole run succeeds. If a recipe fails or is stopped, nothing it stored is kept, and that goes for all the recipes of a page together.
• No lost updates. Runs that use storage take turns per site, so two visitors can't overwrite each other. If a site is very busy, a run may get a 429 instead of waiting.
• Test runs don't save. The editor's test panel reads the real values, and shows what a real run would have saved. Stored values in that panel shows and clears what's there.
• Visitors can fill it up. If keys or values come from visitors through %name%(, check them first: the limit is 1024 KB per site, and when it's full, storing fails.
• It's a file. Values live in .internal/storage.json, which visitors can't reach. It counts towards your storage and is in your downloads. Zip deploys with Replace keep it.

Parameters

Each parameter is checked before the recipe runs, so declare them as narrowly as you can, especially if visitors can call the recipe from JavaScript.

To make a parameter optional, give it a default:

{
  "parameters": {
    "x": "number",
    "y": { "type": "number", "default": 1 }
  },
  "recipe": [
    { "action": "add", "values": ["$x", "$y"] }
  ]
}

Using values

Anywhere a step takes a value, you can use a reference instead of a fixed value, also inside lists and objects:

The result

result can be a reference or a whole structure, which is what you want for returning several things to JavaScript:

{
  "parameters": { "numbers": "list" },
  "recipe": [
    { "action": "min", "values": ["$numbers"], "result": "low" },
    { "action": "average", "values": ["$numbers"], "result": "mean" }
  ],
  "result": { "smallest": "$low", "average": "$mean" }
}

Formatting text

The format action fills in a template. A placeholder takes the next value from values, or a variable by name:

Math actions

The ones marked list also accept a single list: "values": ["$prices"].

Text actions

Converting actions

Logic actions

A recipe runs every step once, top to bottom. There are no loops, but if picks between values:

{
  "parameters": { "total": "numeric[0..inf]" },
  "recipe": [
    { "action": "greater_equal", "values": ["$total", 100], "result": "is_free" },
    { "action": "if", "condition": "$is_free", "then": "free", "else": "4.99 €" }
  ]
}

Data actions

Random actions

{
  "name": "Roll a die",
  "recipe": [
    { "action": "random_int", "values": [1, 6] }
  ]
}

A .chtml page normally keeps its result, but a page where any recipe uses one of these actions runs again on every view, so each visitor gets a new result. Every view then counts towards your limits, and browsers are told not to keep the page.

Hashing actions

Each takes text, and returns its hash as hexadecimal, or as base64 with "output": "base64".

{
  "parameters": { "text": "string" },
  "recipe": [
    { "action": "sha256", "values": ["$text"] }
  ]
}

Password actions

Use these for passwords, never sha256 or md5: those are fast, which is exactly what someone guessing passwords wants. Keep the hash in storage, or in the recipe, like this password gate:

{
  "parameters": { "password": "string" },
  "recipe": [
    { "action": "password_verify", "values": ["$password", "pbkdf2_sha256$600000$AAECAwQFBgcICQoLDA0ODw==$lqWQTC4IyNpCMF28xdfPGOrSY21J9ZUmtgbyZpYoFHM="] }
  ]
}

Each of these takes a noticeable part of a run's time limit, so use one or two per run, and call them with %#name%( so the page doesn't freeze. Never write a real password in a page's %{ }% tag or in its JavaScript: anyone can read those.

Encoding actions

Encoding isn't encryption: anyone can decode it. If decoded data isn't valid text, the decode actions report an error, and the conversions in the last row still work.

{
  "parameters": { "text": "string" },
  "recipe": [
    { "action": "base64_encode", "values": ["$text"] }
  ]
}

Bitwise actions

These work on whole numbers. The ones marked list also accept a single list.

{
  "parameters": { "value": "int" },
  "recipe": [
    { "action": "bit_and", "values": ["$value", 255] }
  ]
}