Aegis documentation

#Live feed — Bird and pulse

Two small daemons make the panel move without polling a database:

  • pulse samples the platform (core, network, nginx, mail,
  • connections) on its own timers and publishes each snapshot;

  • Bird carries every published message to browser sockets as WebSocket
  • frames.

    Producers never talk to a browser, and the browser never talks to a producer. The tasker uses the same transport for its log, so one mechanism serves every live surface.

    #Bird

    A small Rust daemon (aegis-r-bird) that forwards whatever the platform writes to its unix socket. It knows nothing about Aegis, which is what keeps it reusable.

    toml
    [bird]enabled = truelisten = "0.0.0.0"port = 9982private_token = "…"        # required for the private channelmax_clients = 256queue = 64                  # buffered messages per subscriber before it is droppedping_interval = 20          # 0 disables keepalive pingsmax_frame = 1048576level = 6                   # zlib level

    #Producing a message

    Anything on the host writes one line to <run>/bird.sock:

    text
    <channel>\t<topic>\t<json>\n
    python
    from app.modules.bird import publishpublish.send(config, "private", "core", {"at": 1700000000, "…": "…"})

    Delivery is best effort on purpose: a live view that misses one message is corrected by the next snapshot, and a stopped Bird must never block the process that wanted to publish. send returns False when nobody is listening.

    #Channels and topics

    ChannelURLWho may connect
    public/ws/publicanyone
    private/ws/private?token=…holders of bird.private_token

    A socket receives only the topics it subscribed to; a topic is a routing label, not a permission. Current topics:

    TopicProducerContent
    corepulsehost facts, every supervised service, jobs, problems
    networkpulseinterfaces, counters, peers
    nginxpulsenew requests and stub-status counters
    mailpulsedeliveries, queue depth, events
    connectionspulseestablished sockets grouped by address
    taskertaskerone log line, or a status change of one task

    #Frame format

    Every server frame is binary: one codec byte, then either the JSON body (0x00) or a 32-bit little-endian original size followed by a zlib stream (0x01). Browsers expand it with DecompressionStream("deflate") — no library and no negotiation. A slow subscriber that fills its queue is dropped instead of being allowed to grow without bound.

    #Pulse

    aegis-pulse samples each area and publishes it under its own topic. Every area has an interval, so a five-second host readout does not share a timer with a minute-level mail summary, and a slow sampler never delays the others.

    toml
    [pulse]enabled = trueinterval = 10       # fallback for an area without its own value[pulse.core]interval = 5
    bash
    aegis pulse status          # what each area published lastaegis pulse daemon          # foreground

    A sampler that raises is reported in its payload (error) instead of breaking the loop; one broken area must not silence the rest.

    #In the panel

    The browser asks /api/live for the connection details — URL, path, channel, token, ping interval — after it is authenticated, so the private token is never baked into a page. A page served over TLS reaches Bird through the same-origin /ws proxy nginx provides, because a browser refuses a ws:// socket from an https:// page.

    Components use one client:

    javascript
    const live = this.app.liveFeed();live.on("core", (data) => this.apply(data));live.onStatus((state) => this.dot(state));live.connect();

    on(topic, handler) returns an unsubscribe function; onStatus reports connecting, open, reconnecting, closed, unauthorized, error and disabled. The client reconnects with a capped backoff, and a socket that opens and closes immediately does not reset it.

    PageTopic
    Dashboardcore
    Monitorconnections, nginx, mail
    Networknetwork
    Task detailtasker

    #Adding a topic

  • Publish it from the producer (pulse, tasker, a job) with a name matching
  • [a-z0-9._-].

  • Subscribe in the page's component with live.on("name", handler).
  • Nothing else: Bird forwards whatever it is given, and the token already covers
  • the private channel.

    #Troubleshooting

    bash
    aegis keeper status            # is aegis-pulse and aegis-r-bird up?aegis pulse status             # did the area publish anything?
  • unauthorized in the browser console: the token changed; reload the page so
  • /api/live hands out the new one.

  • A page that renders once and never updates: the area is disabled or the
  • sampler returns early — check aegis pulse status and <logs>/pulse.log.

  • A dial that freezes: the socket is gone and the client is reconnecting; the
  • status handler should show it.