Guide Sockets

Sockets

ARO provides built-in TCP socket support for bidirectional real-time communication. This chapter covers socket servers and clients.

Socket Server

Starting a Server

Listen for TCP connections in Application-Start:

(Application-Start: Socket Server) {
    Listen on port 9000 as <socket-server>.
    Log "Socket server listening on port 9000" to the <console>.
    Return an <OK: status> for the <startup>.
}

Connection Events

Socket servers emit events for connection lifecycle:

Event	When Triggered
ClientConnected	Client connects
DataReceived	Data received from client
ClientDisconnected	Client disconnects

Handling Connections

(Handle Connection: ClientConnected Handler) {
    Extract the <connection-id> from the <event: connectionId>.
    Extract the <remote-address> from the <event: remoteAddress>.

    Log "Client connected: ${remote-address}" to the <console>.

    (* Send welcome message *)
    Send the <welcome> to the <event: connection> with "Welcome to the server!".

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

Receiving Data

(Handle Data: DataReceived Handler) {
    Extract the <data> from the <event: data>.
    Extract the <connection> from the <event: connection>.
    Extract the <connection-id> from the <event: connectionId>.

    Log "Received from ${connection-id}: ${data}" to the <console>.

    (* Process the data *)
    Process the <response> from the <data>.

    (* Send response back *)
    Send the <response> to the <connection>.

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

Handling Disconnections

(Handle Disconnect: ClientDisconnected Handler) {
    Extract the <connection-id> from the <event: connectionId>.
    Extract the <reason> from the <event: reason>.

    Log "Client ${connection-id} disconnected: ${reason}" to the <console>.

    (* Clean up client state *)
    Delete the <client-state> from the <client-registry> where id = <connection-id>.

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

Socket Client

Connecting to a Server

(Connect to Server: External Service) {
    Connect to <host: "192.168.1.100"> on port 8080 as <server-connection>.

    (* Send initial handshake *)
    Send the <handshake> to the <server-connection> with { type: "hello", client: "my-app" }.

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

Sending Data

(Send Message: Messaging) {
    Create the <message> with {
        type: "chat",
        content: <content>,
        timestamp: <current-time>
    }.

    Send the <message: JSON> to the <server-connection>.

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

Receiving Responses

(Handle Server Response: DataReceived Handler) {
    Extract the <data> from the <event: data>.
    Parse the <message: JSON> from the <data>.
    Extract the <type> from the <message: type>.

    match <type> {
        case "ack" {
            Log "Message acknowledged" to the <console>.
        }
        case "error" {
            Extract the <error> from the <message: error>.
            Log <error> to the <console>.
        }
        case "data" {
            Process the <result> from the <message: payload>.
        }
    }

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

Common Patterns

Echo Server

(Application-Start: Echo Server) {
    Listen on port 9000 as <echo-server>.
    Log "Echo server listening on port 9000" to the <console>.
    Return an <OK: status> for the <startup>.
}

(Echo Data: DataReceived Handler) {
    Extract the <data> from the <event: data>.
    Extract the <connection> from the <event: connection>.

    (* Echo back the received data *)
    Send the <data> to the <connection>.

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

Chat Server

(Application-Start: Chat Server) {
    Listen on port 9000 as <chat-server>.
    Create the <clients> with [].
    Publish as <connected-clients> <clients>.
    Return an <OK: status> for the <startup>.
}

(Register Client: ClientConnected Handler) {
    Extract the <connection> from the <event: connection>.
    Extract the <connection-id> from the <event: connectionId>.

    (* Add to connected clients *)
    Store the <connection> into the <connected-clients> with id <connection-id>.

    (* Notify others *)
    Broadcast the <announcement> to the <chat-server> with "User joined".

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

(Broadcast Message: DataReceived Handler) {
    Extract the <message> from the <event: data>.
    Extract the <sender-id> from the <event: connectionId>.

    Create the <broadcast> with {
        from: <sender-id>,
        message: <message>,
        timestamp: <current-time>
    }.

    (* Send to all connected clients *)
    Broadcast the <broadcast: JSON> to the <chat-server>.

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

(Remove Client: ClientDisconnected Handler) {
    Extract the <connection-id> from the <event: connectionId>.

    (* Remove from connected clients *)
    Delete the <client> from the <connected-clients> where id = <connection-id>.

    (* Notify others *)
    Broadcast the <announcement> to the <chat-server> with "User left".

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

Protocol Handler

(Handle Protocol: DataReceived Handler) {
    Extract the <raw-data> from the <event: data>.
    Extract the <connection> from the <event: connection>.

    (* Parse protocol message *)
    Parse the <message: JSON> from the <raw-data>.
    Extract the <type> from the <message: type>.
    Extract the <payload> from the <message: payload>.

    match <type> {
        case "ping" {
            Send the <pong> to the <connection> with { type: "pong" }.
        }
        case "auth" {
            Validate the <payload> for the <auth-schema>.
            Send the <auth-success> to the <connection> with { type: "auth_ok" } when <validation> is success.
            Send the <auth-failed> to the <connection> with { type: "auth_fail" } when <validation> is not success.
        }
        case "subscribe" {
            Extract the <channel> from the <payload: channel>.
            Subscribe the <connection> to the <channel>.
            Send the <subscribed> to the <connection> with { type: "subscribed", channel: <channel> }.
        }
        case "publish" {
            Extract the <channel> from the <payload: channel>.
            Extract the <data> from the <payload: data>.
            Publish the <data> to the <channel>.
        }
    }

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

Client Reconnection

(Application-Start: Resilient Client) {
    Connect to <host: "server.example.com"> on port 9000 as <server>.
    Return an <OK: status> for the <startup>.
}

(Handle Disconnect: ClientDisconnected Handler) {
    Extract the <reason> from the <event: reason>.
    Log "Disconnected: ${reason}. Reconnecting..." to the <console>.

    (* Wait before reconnecting *)
    Wait for 5 seconds.

    (* Attempt reconnection *)
    Connect to <host: "server.example.com"> on port 9000 as <server>.

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

Data Formats

Text Data

Send the <text> to the <connection> with "Hello, World!".

JSON Data

Create the <message> with {
    type: "update",
    data: { value: 42 }
}.
Send the <message: JSON> to the <connection>.

Binary Data

Read the <binary: bytes> from the <file: "./data.bin">.
Send the <binary> to the <connection>.

Broadcasting

To All Clients

Broadcast the <message> to the <socket-server>.

To Specific Clients

(* Send to specific connection *)
Send the <message> to the <connection>.

(* Send to connection by ID *)
Retrieve the <client> from the <connected-clients> where id = <client-id>.
Send the <message> to the <client: connection>.

Connection Management

Tracking Connections

(Track Connection: ClientConnected Handler) {
    Extract the <connection> from the <event: connection>.
    Extract the <connection-id> from the <event: connectionId>.
    Extract the <remote-address> from the <event: remoteAddress>.

    Create the <client-info> with {
        id: <connection-id>,
        address: <remote-address>,
        connection: <connection>,
        connectedAt: <current-time>
    }.

    Store the <client-info> into the <client-registry>.

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

Closing Connections

(Kick Client: Admin Action) {
    Extract the <client-id> from the <request: parameters>.
    Retrieve the <client> from the <client-registry> where id = <client-id>.

    Send the <kick-notice> to the <client: connection> with "You have been disconnected" when <client> is not empty.
    Close the <client: connection> when <client> is not empty.
    Delete the <client> from the <client-registry> where id = <client-id> when <client> is not empty.

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

Best Practices

Handle Connection Errors

(Connect to Server: Client Setup) {
    Connect to <host: "server.example.com"> on port 9000 as <server>.

    Log "Failed to connect to server" to the <console> when <server> is empty.
    Return a <ServiceUnavailable: status> for the <connection: error> when <server> is empty.

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

Validate Incoming Data

(Handle Data: DataReceived Handler) {
    Extract the <raw-data> from the <event: data>.

    (* Validate data format *)
    Parse the <message: JSON> from the <raw-data>.

    Log "Invalid message format" to the <console> when <message> is empty.
    Return an <OK: status> for the <validation> when <message> is empty.

    Validate the <message> for the <message-schema>.

    Send the <error> to the <event: connection> with { error: "Invalid message" } when <validation> is failed.
    Return an <OK: status> for the <validation> when <validation> is failed.

    (* Process valid message *)
    Process the <result> from the <message>.
    Return an <OK: status> for the <processing>.
}

Clean Up on Shutdown

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

    (* Notify all clients *)
    Broadcast the <shutdown-notice> to the <socket-server> with "Server shutting down".

    (* Close server *)
    Close the <socket-server>.

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

Next Steps

• Events - Event-driven patterns
• HTTP Services - HTTP communication
• Application Lifecycle - Startup and shutdown