You are reading the documentation for an outdated Corteza release. 2024.9 is the latest stable Corteza release.

Corteza Server

Corteza server is mainly responsible for:

  • Providing endpoints for fetching scripts and script execution,

  • scheduling deferred automation scripts,

  • requesting script execution on the Corredor server.

The following automation scripts are executed directly by the Corteza server:

  • Implicit server-scripts,

  • explicit server-scripts,

  • deferred scripts,

  • sink scripts, and

  • iterator scripts.

Security context

Script endpoints

[APPLICATION NAME]/automation/list

Provides a list of available automation scripts for the given Corteza application.

[APPLICATION NAME]/automation/{bundle}-{type}.{ext}

Provides the client-script automation bundle for the given Corteza application.

If the given application doesn’t have it’s own bundle, the endpoint returns a 404 not found.
[APPLICATION NAME]/automation/trigger

Requests explicit server-script execution on the Corredor server.

system/sink

Provides an endpoint that server-scripts are able to listen on and perform operations for.

Event bus

Any executable automation script is registered on the event bus. Whenever any part of the system might require a script execution, it dispatches an event on the event bus and any registered script that conforms to the requirements is executed on the Corredor server.

The script registration flow is as follows:

Fetch available scripts from the Corredor server

This provides a full automation script list, including invalid scripts (those that didn’t compile successfully) — these are excluded.

Prepare a lightweight script representation

Define a lightweight handler struct for easier execution determination and script identification. Execution is performed by the handler function that allows a bit more flexibility on how to handle each script type.

Note that the iterators handler function is a bit more complex than the rest.
Register the script on the event bus

Register the above simplified automation script on the event buss.

Now when it comes to script execution, this is invoked by dispatching an event on the event bus. To outline the flow:

Dispatch the event on the event bus

An event is a generic interface that allows the event bus to determine what scripts should be executed.

Execute the scripts

Iterate and execute any automation script that conforms to the dispatched event. This can be done either synchronously or asynchronously.

Server side script execution

If the result of an automation script is an Aborted error, the current script should not effect the system’s state, but it also should not terminate any further execution.
Explicit

Explicit scripts are invoked by the front-end applications or manually via the API. When invoked, an event is constructed and dispatched via the event bus.

This is also true for sink script execution.
Implicit

These are triggered as a side-effect of another operation, such as record creation, user registration, password change, …​ Each part of the system that performs some operation that may invoke script execution generates an event and dispatches it on the event bus.

The same is also true for the Scheduler.
Iterator

Iterator script execution is invoked like any other deferred script. The important difference is that a new instance is executed for every resource that matches the trigger’s constraints.

If 10 records match the provided filter, the script will be executed 10 times.

System sink

System sink allows the implementation of custom endpoints on the Corteza server. This can be used for things like webhooks.

This works like so:

  1. intercept any HTTP request on the /sink endpoint,

  2. basic request validation (provided required parameters),

  3. validate request against the sink’s signature,

  4. process request based on:

    • Content-Type or any other HTTP header,

    • remote address (IP),

    • request method and path,

    • username and password (HTTP basic auth),

    • GET (query string) parameters,

    • POST parameters,

  5. generate an event and dispatch it via the event bus.

Scheduler

The scheduler system is responsible for triggering deferred scripts. At it’s core, scheduler is a "simple" ticker that dispatches periodical event on the event bus.

The interval is "hard-coded" to 1minute but that can be made configurable in the future.

There is no mechanism in place that would prevent the automation scripts to overlap.

For example:

  • Script A runs every minute and the execution takes 1.5min,

  • on first tick, script A is executed,

  • on second tick, script A is executed again along side the old instance.

This could be improved in the future.