# Yaml preprocessing


The `yamlPreprocessor` option in your project & service import YAML allows you to generate random secret values, passwords, and public/private key pairs for your secret environment variables.

---

## How does it work?

The `yamlPreprocessor=on` is required as the first line in your import YAML to enable the preprocessor.

```yaml
#yamlPreprocessor=on
project:
  name: project
services:
  - hostname: app
    type: nodejs@latest
    buildFromGit: https://github.com/example/app
    enableSubdomainAccess: true
    envSecrets:
      # yamlPreprocessor feat: generates a random 64 char and stores it
      SECRET_KEY: <@generateRandomString(<64>)>
    
  - hostname: db
    type: postgresql@16
    mode: HA
```

After you've added the `yamlPreprocessor=on` line, the preprocessor will be enabled and you can now utilize the functions.

---

### How Preprocessing Works

The YAML script processing happens in two sequential steps. During the first turn (preprocessing), the system scans for Zerops import functions and modifiers, evaluates them, and replaces function calls with their results. All this data is stored in memory.

The second turn handles standard processing, where the system creates the imported project, instantiates all required services, and handles environment variables, including setting up any new ones as needed.

### Syntax Reference

<table className="w-full my-1.5 ">
  <thead>
    <tr className="">
      <th className="w-fit">Sequence</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody className="">
    <tr>
      <td className="w-fit">`<@`</td>
      <td className="w-fit ">The identifier of the beginning of a function expression syntax.</td>
    </tr>
    <tr>
      <td className="w-fit">`(`</td>
      <td className="w-fit">The identifier of the beginning of the function parameters.</td>
    </tr>
    <tr>
      <td className="w-fit">`)`</td>
      <td className="w-fit">The identifier of the end of the function parameters.</td>
    </tr>
    <tr>
      <td className="w-fit">`,`</td>
      <td className="w-fit">A function parameters delimiter.</td>
    </tr>
    <tr>
      <td className="w-fit">`<`</td>
      <td className="w-fit">Identifier of the beginning of a string expression (without @).</td>
    </tr>
    <tr>
      <td className="w-fit">`>`</td>
      <td className="w-fit">The identifier of the end of a string expression or a function expression syntax.</td>
    </tr>
    <tr>
      <td className="w-fit">`|`</td>
      <td className="w-fit">The separator between a string or a function expression content and a modifier name.</td>
    </tr>
    <tr>
      <td className="w-fit">`\`</td>
      <td className="w-fit">Escaping character.</td>
    </tr>
    <tr>
      <td className="w-fit">`\<>|`</td>
      <td className="w-fit">Characters that need to be escaped to print them out.</td>
    </tr>
  </tbody>
</table>

:::note
All functions in the preprocessor return values as strings, regardless of the operation performed. This includes numeric operations, random generation, and variable manipulation.
:::

---

## Parameter Data Types

Functions generally support 2 types of parameters.

### String expressions

- Value is enclosed in `<` and `>` characters.
- Spaces between `<` and `>` are NOT trimmed.
- When the value is passed as a function parameter, it's always a string.

```yaml
# String expression: <16>
SECRET_KEY: <@generateRandomString(<16>)>
# String expressions: <1> and <100>
RANDOM_RANGE: <@generateRandomInt(<1>, <100>)>
# String expressions: <red>, <green>, <blue>
PICK_VALUE: <@pickRandom(<red>, <green>, <blue>)>
```

### Variable reference names

Variables are used to store and reuse values across your configuration. They can be created using functions like `setVar` and retrieved using `getVar`.

- Variable references are NOT enclosed in `<` and `>` when used with `getVar`
- Variable names are case-sensitive
- Spaces before and after the reference name are trimmed
- Returns an error if the variable doesn't exist

```yaml
# Stores a value in myPassword variable
PASSWORD: <@setVar(<myPassword>, <@generateRandomString(<30>)>)>

# Retrieves the stored value (myPassword)
HASHED_PASSWORD: <@getVar(myPassword)|sha256>
# Reuses the stored value (myPassword)
SAME_PASSWORD_AGAIN: <@getVar(myPassword)>
```

:::tip Internal processing of function parameters
All parameters are handled as strings internally. For functions that expect numbers (like `generateRandomString`), the string values are automatically converted to numbers during processing.
:::

---

## Nested Expressions

The preprocessor supports nested function and string expressions, allowing you to:
- Combine multiple functions
- Use function outputs as inputs for other functions
- Nest string expressions within other strings
- Create complex, multi-level expressions

### Examples of Nesting with Environment Variables

```yaml
#yamlPreprocessor=on
services:
- hostname: app
  type: nodejs@20
  envSecrets:
    NESTED_STRINGS: 
</Dropdown>

---

:::tip Example Usage for Environment Variables
- For Multiline Generation use:
```yaml
APP_PUBLIC_KEY: |
      <@getVar(KeyPublic)>
```

- For Single Value Generation use:
```yaml
APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
```
:::

---

### generateED25519Key (name)

Generates public and private [ED25519](https://en.wikipedia.org/wiki/EdDSA) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateED25519Key(
  
</Dropdown>

---

### generateRSA2048Key (name)

This Generates public and private [RSA 2048bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRSA2048Key(
  
</Dropdown>

---

### generateRSA4096Key (name)

This Function Generates public and private [RSA 4096bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">Syntax:</td>
      <td className="w-fit">`<@generateRSA4096Key(
  
</Dropdown>

## Import modifiers

Modifiers provide a simpler way to transform values compared to using functions alone. You can chain multiple modifiers together using the `|` symbol, making it easy to apply several transformations in sequence. They work with both string and function expressions - just add them between the `<` and `>` markers, right before the closing `>`.

---

### List of import modifiers

<table className="w-full my-1.5 ">
  <thead>
    <tr>
      <th className="w-fit">Name</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">sha256</td>
      <td className="w-fit">Generate a hash of the incoming string using [sha256](https://en.wikipedia.org/wiki/SHA-2) algorithm.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">sha512</td>
      <td className="w-fit">Generate a hash of the incoming string using [sha512](https://en.wikipedia.org/wiki/SHA-2) algorithm.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">bcrypt</td>
      <td className="w-fit">
        Generate a hash of the incoming string using [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm.

        Fixed configuration: Number of cycles = 11
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">argon2id</td>
      <td className="w-fit">
        Generate a hash of the incoming string using [argon2id](https://en.wikipedia.org/wiki/Argon2) algorithm.

        Fixed configuration: Memory = 64MiB, Iterations = 4, Parallelism = 4, SaltLen = 16B, KeyLength = 32B
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">toHex</td>
      <td className="w-fit">Encodes provided string/bytes into hexadecimal</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">toString</td>
      <td className="w-fit">Encodes provided string/bytes into string comprised of [a-zA-Z0-9_-.]</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">upper</td>
      <td className="w-fit">Maps all unicode letters to their upper case</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">lower</td>
      <td className="w-fit">Maps all unicode letters to their lower case</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">title</td>
      <td className="w-fit">Maps all words to title case (first letter upper case, rest lower case)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">noop</td>
      <td className="w-fit">Does nothing - used in tests</td>
    </tr>
  </tbody>
</table>

---

### Examples of correctly using import modifiers

</Dropdown>

:::tip Using a space before the pipe separator
As you can see above, unlike the case of the string expression, using a space before the `|` separator in a function expression doesn't add an additional space character to the result.
:::