Skip to content

Reference System Objects

Jump to bottom
Kris Simon edited this page Jan 4, 2026 · 4 revisions

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 Environment variables 
(* Read an environment variable *)
<Extract> the <api-key> from the <env: API_KEY>.

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

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 Metadata

{
  "services": [...],
  "systemObjects": [
    {
      "identifier": "redis",
      "description": "Redis key-value store",
      "capabilities": ["readable", "writable"],
      "readSymbol": "redis_read",
      "writeSymbol": "redis_write"
    }
  ]
}

Plugin Implementation

import Foundation

@_cdecl("redis_read")
public func redisRead(
    _ propertyPtr: UnsafePointer<CChar>?,
    _ resultPtr: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>
) -> Int32 {
    let key = propertyPtr.map { String(cString: $0) } ?? ""

    // Your Redis read logic here
    guard let value = RedisClient.shared.get(key) else {
        return 1 // Not found
    }

    resultPtr.pointee = strdup(value)
    return 0
}

@_cdecl("redis_write")
public func redisWrite(
    _ valuePtr: UnsafePointer<CChar>,
    _ resultPtr: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>
) -> Int32 {
    let value = String(cString: valuePtr)

    // Your Redis write logic here
    RedisClient.shared.set(value)
    return 0
}

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

Home

Getting Started

Language Guide

Fundamentals

Runtime & Events

I/O & Communication

Advanced

Language Reference

Extending ARO

Clone this wiki locally