Guide Application Lifecycle

Application Lifecycle

ARO applications have a well-defined lifecycle from startup to shutdown. This chapter explains how to manage your application's lifecycle.

Lifecycle Overview

┌─────────────────────────────────────────────────────┐
│                 Application Lifecycle               │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. Load all .aro files                             │
│  2. Compile and validate                            │
│  3. Register feature sets with event bus            │
│  4. Execute Application-Start                       │
│  5. Enter event loop                                │
│           │                                         │
│           ▼                                         │
│  ┌─────────────────┐                                │
│  │  Handle Events  │◄──── HTTP, Files, Sockets,    │
│  │  (event loop)   │       Domain Events            │
│  └────────┬────────┘                                │
│           │                                         │
│           ▼ (shutdown signal)                       │
│                                                     │
│  6. Stop accepting new events                       │
│  7. Wait for pending events                         │
│  8. Execute Application-End                         │
│  9. Stop services                                   │
│  10. Exit                                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Application-Start

The entry point for every ARO application.

Requirements

• Exactly one per application
• Must be named Application-Start
• Must return a status

Basic Example

(Application-Start: My Application) {
    <Log> "Starting application..." to the <console>.
    <Return> an <OK: status> for the <startup>.
}

Full Example

(Application-Start: E-Commerce Platform) {
    <Log> "Starting E-Commerce Platform..." to the <console>.

    (* Load configuration *)
    <Read> the <config: JSON> from the <file: "./config.json">.
    <Publish> as <app-config> <config>.

    (* Initialize database connection *)
    <Connect> to <host: "${config.database.host}"> on port <config: database.port> as <database>.

    (* Start HTTP server *)
    <Start> the <http-server> on port <config: server.port>.

    (* Start file watcher for uploads *)
    <Watch> the <directory: "./uploads"> as <upload-watcher>.

    (* Start background scheduler *)
    <Start> the <scheduler>.

    <Log> "Platform ready on port ${config.server.port}" to the <console>.
    <Return> an <OK: status> for the <startup>.
}

Initialization Order

Statements execute sequentially, so order matters:

(Application-Start: Ordered Initialization) {
    (* 1. Load config first - other steps depend on it *)
    <Read> the <config> from the <file: "./config.json">.
    <Publish> as <app-config> <config>.

    (* 2. Initialize database - services need it *)
    <Connect> to <database-host> as <database>.

    (* 3. Start services - they use config and database *)
    <Start> the <http-server> on port <config: port>.

    <Return> an <OK: status> for the <startup>.
}

Application-End

Exit handlers for cleanup when the application stops.

Success Handler

Called on graceful shutdown (SIGTERM, SIGINT, or programmatic stop):

(Application-End: Success) {
    <Log> "Shutting down gracefully..." to the <console>.

    (* Stop accepting new requests *)
    <Stop> the <http-server>.

    (* Close database connections *)
    <Close> the <database-connections>.

    <Log> "Shutdown complete. Goodbye!" to the <console>.
    <Return> an <OK: status> for the <shutdown>.
}

Error Handler

Called when the application crashes or encounters a fatal error:

(Application-End: Error) {
    <Extract> the <error> from the <shutdown: error>.
    <Extract> the <code> from the <shutdown: code>.
    <Extract> the <reason> from the <shutdown: reason>.

    <Log> "FATAL ERROR: ${reason}" to the <console>.
    <Log> <error> to the <console>.

    (* Send alert to operations *)
    <Send> the <crash-alert> to the <ops-webhook> with {
        service: "E-Commerce Platform",
        error: <error>,
        code: <code>,
        reason: <reason>,
        timestamp: <current-time>
    }.

    (* Attempt graceful cleanup *)
    <Close> the <database-connections>.

    <Return> an <OK: status> for the <error-handling>.
}

Shutdown Context

Available variables in Application-End handlers:

Variable	Description	Available In
<shutdown: reason>	Human-readable reason	Both
<shutdown: code>	Exit code (0 = success)	Both
<shutdown: signal>	Signal name (SIGTERM, etc.)	Success
<shutdown: error>	Error object	Error only

Rules

• Both handlers are optional
• At most one of each per application
• Error handler only runs on errors
• Success handler only runs on graceful shutdown

Running Applications

Basic Run

aro run ./MyApp

The application runs and exits when Application-Start completes.

Keeping Applications Alive

For servers that should run indefinitely, use the <Keepalive> action:

(Application-Start: My Server) {
    <Start> the <http-server> on port 8080.
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

The <Keepalive> action blocks until interrupted (Ctrl+C or kill signal).

Graceful Shutdown

When you send SIGTERM or SIGINT:

1. The event loop stops accepting new events
2. Pending events complete (with timeout)
3. Application-End: Success executes
4. Services stop
5. Application exits with code 0

Error Shutdown

When an unhandled error occurs:

1. The error is caught
2. Application-End: Error executes
3. Services stop (best effort)
4. Application exits with non-zero code

Service Initialization

HTTP Server

(Application-Start: Web Server) {
    <Start> the <http-server> on port 8080.
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(Application-End: Success) {
    <Stop> the <http-server>.
    <Return> an <OK: status> for the <shutdown>.
}

File Watcher

(Application-Start: File Processor) {
    <Watch> the <directory: "./inbox"> as <file-watcher>.
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(Application-End: Success) {
    <Stop> the <file-watcher>.
    <Return> an <OK: status> for the <shutdown>.
}

Socket Server

(Application-Start: Socket Server) {
    <Listen> on port 9000 as <socket-server>.
    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(Application-End: Success) {
    <Close> the <socket-server>.
    <Return> an <OK: status> for the <shutdown>.
}

Multiple Services

(Application-Start: Full Stack) {
    (* HTTP API *)
    <Start> the <http-server> on port 8080.

    (* WebSocket server *)
    <Listen> on port 8081 as <websocket-server>.

    (* File watcher *)
    <Watch> the <directory: "./uploads"> as <upload-watcher>.

    (* Background jobs *)
    <Start> the <job-scheduler>.

    (* Keep the application running *)
    <Keepalive> the <application> for the <events>.

    <Return> an <OK: status> for the <startup>.
}

(Application-End: Success) {
    (* Stop in reverse order *)
    <Stop> the <job-scheduler>.
    <Stop> the <upload-watcher>.
    <Close> the <websocket-server>.
    <Stop> the <http-server>.

    <Return> an <OK: status> for the <shutdown>.
}

Configuration Loading

From File

(Application-Start: Configured App) {
    <Read> the <config: JSON> from the <file: "./config.json">.
    <Publish> as <app-config> <config>.

    <Start> the <http-server> on port <config: port>.
    <Return> an <OK: status> for the <startup>.
}

From Environment

(Application-Start: Environment Config) {
    <Extract> the <port> from the <environment: PORT>.
    <Extract> the <db-url> from the <environment: DATABASE_URL>.

    <Connect> to <db-url> as <database>.
    <Start> the <http-server> on port <port>.

    <Return> an <OK: status> for the <startup>.
}

With Defaults

(Application-Start: Config with Defaults) {
    <Extract> the <port> from the <environment: PORT>.

    <Set> the <port> to 8080 when <port> is empty.

    <Start> the <http-server> on port <port>.
    <Return> an <OK: status> for the <startup>.
}

Health Checks

Set up health check endpoints using contract-first HTTP. Define routes in openapi.yaml:

openapi.yaml:

paths:
  /health:
    get:
      operationId: healthCheck
  /ready:
    get:
      operationId: readinessCheck

main.aro:

(Application-Start: Healthy App) {
    <Set> the <startup-time> to <current-time>.
    <Publish> as <app-startup-time> <startup-time>.

    <Keepalive> the <application> for the <events>.
    <Return> an <OK: status> for the <startup>.
}

(healthCheck: Health API) {
    <Create> the <health> with {
        status: "healthy",
        uptime: <current-time> - <app-startup-time>,
        version: "1.0.0"
    }.
    <Return> an <OK: status> with <health>.
}

(readinessCheck: Health API) {
    (* Check dependencies *)
    <Check> the <database-connection>.
    <Check> the <cache-connection>.

    <Return> a <ServiceUnavailable: status> with { ready: false } when <checks: allPassed> is false.
    <Return> an <OK: status> with { ready: true }.
}

Best Practices

Initialize Early, Fail Fast

(Application-Start: Fail Fast) {
    (* Check critical config first *)
    <Read> the <config> from the <file: "./config.json">.

    when <config: database> is empty {
        <Log> "Missing database configuration" to the <console>.
        <Throw> a <ConfigurationError> for the <missing: database>.
    }

    (* Then initialize services *)
    <Connect> to <config: database.url> as <database>.
    <Start> the <http-server> on port <config: port>.

    <Return> an <OK: status> for the <startup>.
}

Clean Shutdown

(Application-End: Success) {
    <Log> "Initiating graceful shutdown..." to the <console>.

    (* 1. Stop accepting new work *)
    <Stop> the <http-server>.

    (* 2. Wait for in-progress work *)
    <Wait> for the <pending-requests> with timeout 30.

    (* 3. Close external connections *)
    <Close> the <database-connections>.
    <Close> the <cache-connections>.

    <Log> "Shutdown complete" to the <console>.
    <Return> an <OK: status> for the <shutdown>.
}

Log Lifecycle Events

(Application-Start: Observable App) {
    <Log> "APPLICATION_STARTING" to the <console>.

    <Start> the <http-server> on port 8080.

    <Log> "APPLICATION_READY" to the <console>.
    <Return> an <OK: status> for the <startup>.
}

(Application-End: Success) {
    <Log> "APPLICATION_STOPPING" to the <console>.

    <Stop> the <http-server>.

    <Log> "APPLICATION_STOPPED" to the <console>.
    <Return> an <OK: status> for the <shutdown>.
}

Next Steps

• HTTP Services - HTTP server and client
• File System - File operations and watching
• Events - Event-driven architecture