Execution semantics, constraints, and security

This page summarizes how a Script behaves at runtime (order, transactions, errors, locking), what static constraints it is subject to at save time, and its security model. For syntax, see the Statement Catalog and value expressions; for practical combinations, see the cookbook.

Execution order

• statements run sequentially from top to bottom. When execution reaches a Return, it stops at that point.
• Execution happens inline, on the path that handles the calling request. The response to the call is the execution result (for the shape of the response, see Request and response in the Script overview), and the time allowed for a single execution is covered in Time budget below.

Execution semantics

Guard (preconditions)

There is no dedicated guard Statement. You express one with If and then:[Return]. When the condition is violated, it returns a result and does not run the subsequent Statements (a Script with no guard is of course also possible).

{ "type": "If", "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" }, "statusCode": 402 } ] }

No transactions and best-effort compensation

A Script is not a transaction. On failure, the engine attempts to compensate for the work done so far and returns the cause of the error, but with the following limits (accepted as a design trade-off).

• Undoing a delete creates a new sys.id, so references that pointed to it break.
• External effects (Http) are irreversible (a call that has already gone out, and its charges, cannot be undone).
• The compensation may not run at all, leaving an uncompensated state.

If you need true atomicity, write the compensation into the Script yourself, or put irreversible operations (such as external calls) last. The most dangerous ordering is the kind that "chains through but cannot roll back, yet looks safe."

Optimistic locking

You narrow update/patch contention with the version on ResourceUpdate and ResourcePatch. If you supply version (a value expression, Int), the update proceeds only when it matches the target's current sys.version; a mismatch aborts with a version-conflict error (which you can handle locally with Try/catch). If you omit it, it is last-write-wins with no check. Typically you read first with ResourceRead or ResourceFind and pass that sys.version (see Optimistic-locking CAS in the cookbook).

Writes go to origin

Writes always land in origin (draft), and exposure on delivery (CDA/ACDA) is controlled by publish (the publish on ResourceCreate/ResourceUpdate/ResourcePatch, or ResourcePublish/ResourceUnpublish).

What counts as a failure

When a single Statement fails during execution, execution stops at that point unless a Try handles the failure. The engine then attempts to undo the work performed up to that point. Undoing has limits, which are covered in No transactions and best-effort compensation.

If the failed Statement is inside a Try, you can handle the failure in catch. Inside a catch, you reference the failure details ({ message }) via /error. It does not carry which Statement failed.

The following cases are treated as failures.

• A resource operation fails (no such target, a version mismatch, an unsupported operation, and so on)
• An Http fails (see Two ways an Http fails)
• A Media file transformation fails (see When a file transformation fails)
• A runtime limit set for each Statement is exceeded (for example, the value length limits)

A Return is not a failure. It ends execution early in the normal way, so it does not pass to catch.

Two ways an Http fails

An Http failure falls into one of two kinds, depending on whether it is handled as a status response. This difference determines whether retry and ignoreStatusCode apply.

The conditions under which sending a file fails are covered in detail in Sending a file as the body.

Server-side aggregation: counts only

Counts are done on the server by ResourceCount. It does not read the items, so it is not subject to the processed-item ceiling.

Sum and group-by have no dedicated server operation. You have to compute such an aggregation yourself, by iterating with ResourceForEach and using SetVar and JsonLogic, so it is bound by the processed-item ceiling (unsuitable for aggregating millions of records). When all you need is a count, use ResourceCount instead of iterating.

No waiting or delay

A Script has no Delay Statement. A Script runs once and is done, and does not wait or poll internally for an external job to finish.

Static constraints (validated at save time)

The following are checked when a Script is saved (on create/update). If any is violated, the save is rejected (this fails at authoring time, not at runtime). Which violation is rejected with which code is covered in Errors.

The fixed limits in the table above are values the platform sets, so they are the same regardless of plan. The maximum total Statements and maximum external calls per definition, by contrast, are per-plan limits. These two are not validation errors but plan limits, so exceeding them causes the save/update to be rejected as a plan-limit overage (the same definition is allowed on a higher plan) and is lifted by upgrading. The per-plan numbers are in Pricing.

Media file ingestion, unlike external calls such as Http and EmailSend, does not count toward the per-definition external-call limit.

ResourceForEach is a composite Statement that owns children, so it itself does not count toward the number of external calls. The external-call Statements inside onEach (Http, EmailSend) are what count (statically counted as 1, but actually executed per item during iteration). onEach can hold external calls or Media file ingestion, and the same is true of a Loop body. How many laps an iteration actually runs does not enter this count; it enters the time budget below as a multiplication instead.

Value length limits (runtime)

The signing and text-processing Statements, and Cache, cap the size of the value they handle. The cap applies to what the expression resolves to, not to the length of the expression (the sixteen characters of { /rawPayload } can point at tens of kilobytes), which is why it is checked while running rather than at save time.

• All four behave like any other runtime failure, so Try/catch can handle them locally.
• Signature's cap is sized for the body sizes real providers send (a payment event runs to a few KB, an order webhook to tens of KB). Hash is far narrower because it is the place where a handful of concatenated fields go.
• The 128 characters of Regex.pattern is the save-time check in Static constraints above. That length is not a safety device ((a+)+$ is dangerous in six characters). What bounds a runaway match is the literal-only rule for patterns plus the time budget below; what a length can honestly promise is a size a person can read and review.

Time budget (runtime)

The time allowed for a single execution is at most 180 seconds. The time actually allowed is determined by the Script definition (and, when files are sent, by the plan as well), and equals a base of 30 seconds plus the time that external calls can use.

This budget applies to the execution as a whole. Separately, a single Http request must finish within that request's timeoutMs.

Base of 30 seconds

All work that is not an external call, such as reading and writing resources or receiving and processing Media files, is handled within these 30 seconds. A Script with no external calls is allowed 30 seconds.

Time each Statement adds

The times of Statements placed in sequence all add up.

If there is no external call inside an iteration, the time added is 0 even after multiplying by the number of iterations. Such an iteration must therefore finish within the base 30 seconds.

Download time per file

This value is the time it takes to receive the plan's download limit at 10,000,000 bytes per second.

Calculation example

A Script that calls one Http sending two photos (timeoutMs 30 seconds, retry 1) on the Pro plan is calculated as follows.

• Http: (30 seconds + 10.5 seconds × 2) × 2 = about 102 seconds
• Whole execution: 30 seconds + 102 seconds = about 132 seconds

132 seconds is shorter than 180 seconds, so this Script is allowed 132 seconds.

When it exceeds 180 seconds

Even when the computed value exceeds 180 seconds, the Script is saved and runs. However, once execution reaches 180 seconds, it stops at that point.

Per-plan count limits

For Script, the number per Organization is limited by plan.

Separately from this, the number of Statements and the number of external calls (Http, EmailSend) a single Script definition can contain are also limited by plan. When you save or update a definition, exceeding that plan's limit rejects it; for the concrete numbers, see Pricing.

When the limit is reached, creating a new Script is rejected.

Http file download size

When Http fetches a file to send as the request body from a URL (urlBody, or a url part of multipartBody), the size that can be received per file URL is limited by plan. It follows the plan of the Organization to which the Space that owns the Script belongs.

• The limit applies to each URL separately. If there are several url parts, each file must be within this limit.
• Trying to send a file that exceeds the limit makes that Http fail (see Two ways an Http fails).
• This limit is also the basis for the download time added to the time budget.

Security model

secrets

Secret values such as external API keys, a payment provider's (PG) secret key, webhook signing keys, and precomputed Basic … credentials are not written literally into a Statement. Declare them in the definition's secrets, and read them in a Statement as { /secrets/<key> }. Published test keys go in the same place too. Then, when you switch to the real key, you leave the Statements as they are and change only the value in secrets.

"secrets": [
  { "key": "LLM_API_KEY",            "value": "sk-...",    "description": "API key for LLM calls" },
  { "key": "WEBHOOK_SIGNING_SECRET", "value": "whsec_...", "description": "" }
],
"statements": [
  { "type": "Http", "method": "POST", "url": "https://api.openai.com/v1/chat/completions",
    "headers": [ { "key": "Authorization", "value": "Bearer { /secrets/LLM_API_KEY }" } ],
    "body": { /* ... */ }, "name": "llm" }
]

• Storage: WEEGLOO encrypts value and stores it securely. A Statement reads the original value as { /secrets/<key> }.
• Reads: API responses that return a Script (read, create, update) return value as the original value. Any role that can read that Script can see the value, so keep read permission narrow. Members (ServiceUser) cannot read a Script definition (reading and authoring are CMA-only, and ACMA has no Script API).
• Updates: A full update (PUT) replaces the entire definition. If you send it without secrets, the secret values you declared are deleted, and if a Statement still references one of them as { /secrets/… }, the save is rejected. So send secrets along with every update. Sending back the values from the read response as they are is enough.
• Values during execution: What happens to a value once it is read is decided by the Statements. If you return it with Return, it remains in the execution response and the ScriptLog, and if you put it into SetVar, Cache, or a Content, it remains there as the original value. Send secret values only to the external API that needs them.
• App Bundle: When a Script is packed into an App Bundle, the value of secrets is masked as ******, while key and description are carried as they are. A Script created by installing that App Bundle has its secret values set to ******, so the Statements that read them work only after the installing side puts in the real values. Values written in places outside secrets (the headers of Http, the secret of Signature, and so on) are not masked and are carried as they are.

A single Script can hold up to 20 secrets. The pointer rules are covered in /secrets in Value expressions.

Execution identity and authorization

• Execution identity: during execution, every resource operation is performed under the identity of the user who called /execute. The createdBy/updatedBy of any resource that is created or updated is the caller, and a createdBy: ":self" scope also resolves against the caller. Anonymous calls are the exception. An execution that arrived through /execute/anonymous has no caller, so both resolve against the author instead (Anonymous calls).
• There are two authorization boundaries, and at runtime the engine does not re-check resource permissions per Statement.
  1. At authoring time (save): when a Script is saved, it checks whether the author actually holds the resource and action permissions that its Statements use. If even one is missing, the save is rejected. In other words, a Script that contains an unauthorized operation is never saved in the first place. Every Statement that selects a resource is subject to this check, whether it is a leaf or the block-owning ResourceForEach. A definition you already saved is checked again when you update it, so once a permission has been revoked you can no longer save an edit to that definition.
     • The member directory (ServiceUser) is checked on the settings axis, not through a permission map. To write resource: "ServiceUser" in one of the three read Statements or in ResourceUpdate or ResourcePatch, the author's SpaceRole settings must contain SETTING_SERVICE_LOGIN (or SETTING_ALL); see settings on SpaceRole. The member directory is a Space setting on every other path through the system as well.
     • A Statement that creates or deletes a member cannot be saved under any role. A Script cannot create or delete a member, so it is rejected as a mis-written Statement (400) rather than as missing permission (403). That is to say it is not a gap the author could close by adding a role. The only changes allowed on a member are roleOverride and enableLogin on ResourceUpdate and ResourcePatch (see Working with the member directory).
  2. At call time (/execute): only the caller's Script Execute permission is checked. Without it, the result is 403. Once it passes, per-Statement resource permissions are not checked again at runtime; execution proceeds. This works like function-execution permission in programming. If you have permission to run the function, the permission for each individual operation inside it is not asked again. The anonymous call path has no such check. There is no caller to check, which is why opening that path amounts to publishing one Script without authentication.
• Direct-call blocking (directCallEnabled): if a Script's directCallEnabled is false, the /execute direct call itself is rejected. This gate is applied after the Execute permission check has passed, so the call is blocked even when the caller holds the Execute permission. A caller without that permission receives a 403 before reaching this gate. The gate exists only on that endpoint, so a Webhook's linked action (script) and a Scheduler run it as before. The default is true (direct calls allowed).
• Anonymous calls (anonymousCallEnabled): the default is false. Setting it to true makes that one Script runnable through a dedicated unauthenticated path (/execute/anonymous) as well, and there the execution identity is the author, not the caller. Of the two boundaries above, the call-time check (Execute permission) does not exist on that path, so the real authentication is what the Script does for itself (verifying the signature on what it received). The conditions for turning it on and its save-time rules are covered in Anonymous calls.
• Ownership scope: createdBy: ":self" in a where filter means "only what the current caller created" (for example, reading only your own wallet). This filter cannot be used in a Script that allows anonymous calls. With no caller it resolves to the author, so its original meaning as an ownership scope does not hold.
• Delegated permissions (author beware): combining the two boundaries above, running a Script is equivalent to acting with the author's permissions delegated to it. The caller needs only Execute, and the Statements inside the Script run exactly within the scope the author was authorized for at save time. As a result, a resource operation the caller could not perform on their own can still happen through the Script. Because the permissions granted to the author are the effective reach of that Script, decide carefully what operations you put in a Script.

Summary checklist

Before saving, verify the following.

• If you turned on anonymous calls (anonymousCallEnabled), no where carries createdBy: ":self", and a Statement that verifies what was received (such as Signature) comes first.
• The number of external calls (Http, EmailSend) and the total number of Statements are within your plan's limits, SetVar is 10 or fewer, and Cache is 5 or fewer.
• If you used Cache, you wrote key as a literal and did not place it inside a Loop or a ResourceForEach.
• If you traverse a large set with ResourceForEach, you declared a limit or verified the size can complete.
• If you included an iteration (Loop, ResourceForEach), you checked that it enters the time budget as a multiplication (with no external call, the 30-second base budget is the limit).
• Secret values such as external API keys and signing keys are declared in secrets and read as { /secrets/<key> }. No secret value is written literally into a Statement.
• If you save with a full update (PUT), you sent secrets along with it.
• The message for signature verification is taken from { /rawPayload }, not from /payload.
• If a Statement works with members (ServiceUser), the author holds SETTING_SERVICE_LOGIN and you included no Statement that creates or deletes that resource.
• Irreversible operations (external calls) are placed as late as possible.
• If you send files with Http, you wrote only one request body field (body, urlBody, multipartBody) and checked that each file is within the per-plan download limit.
• If you are worried about update/patch contention, use the version on ResourceUpdate or ResourcePatch.
• If you want to return a result, you specified Return.value.

Errors

These are the codes that come back when the shape of a definition breaks a static constraint and the save is rejected. The codes for breaking the value expression rules are in the errors of Value expressions, and the codes that come back when you call or delete a Script are in the errors of Script resource and endpoints. For codes that are common to every resource, see common errors.

Related documents

• Value expressions: value and condition rules.
• Statement Catalog: the fields and results of each Statement.
• Cookbook: a collection of complete examples.
• Script resources and endpoints: the Script resource structure and HTTP endpoints such as /execute.
• Script overview: the top-level structure and the time allowed for a single execution.