Skip to content
NexusFabric

The effect catalog

An effect is a capability that reaches outside the flow — the network, the process environment, another system. A step that uses one must name it. This page lists every effect name the platform accepts, and says which ones do something.

Why effects are declared

The executor dispatches exactly the effects a step declares, before that step’s body runs. A step that does not declare http_egress cannot make an HTTP request, whatever else it says: no handler is called, no socket is opened, and the message passes through untouched.

Two things follow. A flow file can be read as a list of what the integration is able to do, without reading every step in detail. And granting a new capability is a visible edit, not a side effect of adding a configuration key.

Flow level and step level

effects: appears in two places, and they are not the same thing.

In the front matter it is an allowlist. It bounds what the flow as a whole may do.

On a step it is the instruction. Those are the effects that actually run.

Both are needed. Every effect a step declares must also appear in the front-matter list, or the flow does not compile:

Terminal window
$ nexus validate order-sync.flow.md
order-sync.flow.md:20:1: error: step 'forward': effect 'http_egress' is not declared in flow frontmatter (declared: secret_read)
error: 1 validation error(s)

The reverse is not an error and has no consequence. An effect listed in the front matter that no step uses grants permission for something that never happens.

---
flowmarkdown_version: "0.1"
flow: order-sync
tenant: acme
effects: [secret_read, http_egress]
---


## Step: load-key
effects: [secret_read]
key: partner_api_key


## Step: forward
effects: [http_egress]
endpoint: https://orders.example.com/ingest
method: POST
bearer_token: "{{ ctx.partner_api_key }}"

The catalog

effects: accepts these twelve names and no others; anything else is a parse error.

Effect What the name denotes Usable
http_egress Send an HTTP request and replace the message with the response Yes
grpc_egress Call a gRPC method and replace the message with the response Yes
secret_read Read a secret from the environment into a variable Yes
oauth2_token Fetch an OAuth2 access token into a variable Yes
queue_publish Put the message on another flow’s queue — see Queues Yes
clock Reading the wall clock No
random Producing random values No
http_ingress Receiving an HTTP request No
kv_read Reading from a key-value store No
kv_write Writing to a key-value store No
queue_consume Consuming from a queue No
audit_emit Writing an audit entry No

The seven marked No are names with nothing behind them. They parse, they compile, and they deploy. Put one on a step and the step fails at run time — there is no handler to call:

step 'record': no handler registered for effect AuditEmit

Put one only in the front-matter list and it does nothing whatsoever. Do not build on them.

Nothing you need is hidden behind them. Reading the clock and generating identifiers are built-in functions (now(), uuid()) that need no declaration; inbound HTTP, queue consumption and the audit trail are properties of the platform, not of a step. Putting a message on a queue is the one of those that is a step, and it is queue_publish.

Reaching for an effect you did not declare

It is a compile error. A key belongs to the effect whose handler reads it, and a step that carries the key without naming that effect is refused, with an error that names the effect to declare. The rule, for every effect, is under An unknown key is an error. This step has an endpoint: and a method: and no effects::

## Step: forward
endpoint: https://orders.example.com/ingest
method: POST

The compiler answers, for endpoint: and again for method:: step 'forward': unknown key `endpoint` — `endpoint` is read by `http_egress` — add it to this step's `effects:`.

Adding effects: [http_egress] to the step — and http_egress to the front matter — is what turns it into a call.

Where to go next