Reference System Objects

System Objects Reference

System objects are special objects in ARO that represent external sources and sinks of data. They provide a unified interface for interacting with I/O streams, HTTP requests, files, and plugin-provided resources.

Source/Sink Pattern

ARO uses a consistent pattern for interacting with system objects:

Pattern	Direction	Example
Source	Read FROM object	Extract the <data> from the <request: body>.
Sink	Write TO object	Log "Hello" to the <console>.
Bidirectional	Both	Read/Write the <data> from/to the <file: "./data.json">.

Sink Syntax

Sink actions use a clean syntax where the value comes directly after the verb:

Log "Hello, World!" to the <console>.

(* Variables work too *)
Compute the <greeting> from "Welcome to ARO!".
Log <greeting> to the <console>.

(* Objects and arrays *)
Log { status: "ok", count: 42 } to the <console>.

Sink verbs that support this syntax:

• log, print, output, debug (LogAction)
• write (WriteAction)
• send, dispatch (SendAction)

Built-in System Objects

I/O Streams

Identifier	Type	Description
console	Sink	Standard output stream
stderr	Sink	Standard error stream
stdin	Source	Standard input stream

(* Write to console *)
Log "Starting server..." to the <console>.

(* Write to stderr *)
Log "Warning: config missing" to the <stderr>.

(* Read from stdin *)
Read the <input> from the <stdin>.

Environment

Identifier	Type	Description
env	Source	Process environment variables

The env object exposes the process environment for read access. Use a string qualifier to read a specific variable.

(* Read a single environment variable *)
Extract the <api-key> from the <env: API_KEY>.

(* Read all environment variables *)
Extract the <all-vars> from the <env>.

You can also read environment variables inline in when guards and expressions:

(Application-Start: My App) when <env: DEBUG> = "1" {
    Log "Debug mode enabled" to the <console>.
    Return an <OK: status> for the <startup>.
}

Git Repository

Identifier	Type	Description
git	Bidirectional	Git repository (libgit2). With no qualifier: current working directory. With a string qualifier: explicit repository path.

The <git> object is the source for Retrieve (status, log, branch), Pull, and Clone, and the sink for Stage, Commit, Push, Tag, and Checkout. Mutating actions emit Git events (git.commit, git.push, git.pull, git.checkout, git.tag, git.clone).

(* Default: current working directory *)
Retrieve the <status> from the <git>.

(* Explicit path *)
Retrieve the <log> from the <git: "/srv/projects/my-repo">.

(* Stage and commit *)
Stage  the <files>  to the <git> with ".".
Commit the <commit> to the <git> with "feat: add login flow".

(* Pull / Push (shell out to git CLI) *)
Pull the <updates> from the <git>.
Push the <result>  to   the <git>.

See Guide-Git and ARO-0080 for the full action surface.

Contract (Magic Object)

Identifier	Type	Description
Contract	Source	OpenAPI contract metadata

The Contract magic object provides access to the OpenAPI specification at runtime. It's automatically available in any ARO application with an openapi.yaml file.

Properties:

• Contract.http-server - HTTP server configuration object
  • port - Server port (from OpenAPI servers[0].url)
  • hostname - Server hostname (default: "0.0.0.0")
  • routes - Array of route paths (e.g., ["/users", "/orders"])
  • routeCount - Number of routes defined

(* Start HTTP server from Contract *)
Start the <http-server> with <Contract>.

(* Access Contract properties *)
Log <Contract.http-server.port> to the <console>.
Log <Contract.http-server.routes> to the <console>.

(* Shorthand: <http-server> resolves to Contract.http-server *)
Log <http-server.port> to the <console>.

Note: Contract is a magic system object (always capitalized), meaning it's automatically generated by the runtime from the OpenAPI specification, not explicitly bound by user code.

File System

Identifier	Type	Description
file	Bidirectional	File I/O with format detection

The file object automatically detects the format based on file extension and serializes/deserializes accordingly.

(* Read JSON file *)
Read the <config> from the <file: "./config.json">.

(* Read YAML file *)
Read the <settings> from the <file: "./settings.yaml">.

(* Write data to JSON file *)
Write <data> to the <file: "./output.json">.

(* Write to CSV *)
Write <records> to the <file: "./export.csv">.

Supported formats: .json, .yaml, .yml, .csv, .xml, .toml, .ini, .plist, .sql, .env, .log, .txt

HTTP Context (Request Handlers)

These objects are only available within HTTP request handler feature sets.

Identifier	Type	Description
request	Source	Full HTTP request
pathParameters	Source	URL path parameters
queryParameters	Source	URL query parameters
headers	Source	HTTP headers
body	Source	Request body

(getUser: User API) {
    (* Access path parameters *)
    Extract the <id> from the <pathParameters: id>.

    (* Access query parameters *)
    Extract the <limit> from the <queryParameters: limit>.

    (* Access headers *)
    Extract the <auth> from the <headers: Authorization>.

    (* Access request body *)
    Extract the <data> from the <body>.

    (* Access full request *)
    Extract the <method> from the <request: method>.

    Return an <OK: status> with <user>.
}

Event Context (Event Handlers)

Identifier	Type	Description
event	Source	Event payload
shutdown	Source	Shutdown context

(Send Email: UserCreated Handler) {
    Extract the <user> from the <event: user>.
    Send the <welcome-email> to the <user: email>.
    Return an <OK: status> for the <notification>.
}

(Application-End: Success) {
    Extract the <reason> from the <shutdown: reason>.
    Log <reason> to the <console>.
}

Socket Context (Socket Handlers)

Identifier	Type	Description
connection	Bidirectional	Socket connection
packet	Source	Socket data packet

(Echo Server: Socket Event Handler) {
    Extract the <data> from the <packet>.
    Send <data> to the <connection>.
}

Plugin System Objects

Plugins can provide custom system objects that integrate with ARO's source/sink pattern.

Plugin Implementation

Use the AROPluginKit SDK to declare system objects with the .service() builder. The service methods handle reads and writes:

import AROPluginKit

@AROExport
private let plugin = AROPlugin(name: "redis-plugin", version: "1.0.0", handle: "Redis")
    .service("redis", methods: ["get", "set", "delete"]) { method, input in
        switch method {
        case "get":
            let key = input.with.string("key") ?? ""
            guard let value = RedisClient.shared.get(key) else {
                return .failure(.notFound, "Key not found: \(key)")
            }
            return .success(["value": value])
        case "set":
            let key = input.with.string("key") ?? ""
            let value = input.with.string("value") ?? ""
            RedisClient.shared.set(key, value: value)
            return .success(["stored": true])
        case "delete":
            let key = input.with.string("key") ?? ""
            RedisClient.shared.delete(key)
            return .success(["deleted": true])
        default:
            return .failure(.notFound, "Unknown method: \(method)")
        }
    }

Using Plugin System Objects

(* Read from Redis *)
Get the <session> from the <redis: "session:123">.

(* Write to Redis *)
Set <userData> to the <redis: "user:456">.

System Object Capabilities

Capability	Description
source	Can read data (readable)
sink	Can write data (writable)
bidirectional	Both readable and writable

Error Handling

System object errors are handled by the ARO runtime with descriptive messages:

System object 'redis' is not readable (sink only)
Property 'nonexistent' not found in system object 'request'
System object 'database' is not available in non-HTTP context
Failed to read from system object 'redis': Connection refused

See Also

• Guide: File System
• Guide: HTTP Services
• Guide: Events
• Action Developer Guide