Phase 2: Server Push — Implementation Plan

[SeanTAllen]

Implementation plan for Phase 2 of livery, derived from the design in #3.

Scope

Server-side only. Adds external message delivery to LiveView connections, enabling real-time updates from server-side actors (timers, background jobs, PubSub). Covers Phase 2 deliverables from #3.

Deliverables:

1. handle_info on LiveView trait (default no-op)
2. info behavior on _Connection for external message delivery
3. InfoReceiver interface — public handle for sending messages to a connection
4. Socket.self() — returns the connection's InfoReceiver tag
5. PubSub actor — topic-based publish-subscribe
6. Socket.subscribe(topic) / Socket.unsubscribe(topic)
7. Auto-cleanup of subscriptions on connection close
8. Example: ticker-driven counter with PubSub
9. Tests for PubSub, Socket, and updated tests for modified APIs

Design Decision: PubSub Location

The design (#3) lists PubSub as a "separate library" in scope, but Phase 2 deliverables include socket.subscribe(topic) / socket.unsubscribe(topic). These are in tension.

Options:

(A) Built-in PubSub within livery. A simple PubSub actor in the livery package. Listener accepts it as a parameter and passes it to connections. Socket provides subscribe/unsubscribe convenience methods. Connections auto-cleanup on close.

• Pro: Integrated API, automatic cleanup, no external dependency
• Pro: Matches the Phase 2 deliverables exactly
• Con: Not reusable outside livery

(B) Mechanisms only, no PubSub. Livery provides handle_info, info behavior, socket.self(), and a terminate callback on LiveView. Users wire their own PubSub using the connection reference. No subscribe/unsubscribe on Socket.

• Pro: Follows "separate library" design intent, maximum flexibility
• Con: Defers the Phase 2 deliverables, manual cleanup burden on users

(C) Built-in PubSub now, extract later. Build a simple PubSub within livery for Phase 2. When a standalone PubSub library exists, livery can depend on it instead.

• Pro: Delivers the Phase 2 API now, migration path exists
• Con: Temporary duplication if/when an external PubSub appears

Recommendation: Option C. Delivers the Phase 2 deliverables as designed, keeps the API clean with automatic cleanup, and the PubSub can be extracted later.

Dependencies

No new external dependencies. Uses collections (stdlib) for HashMap/HashSet in PubSub (imported as use collections = "collections" per project qualified-import convention). Uses time (stdlib) for the ticker example.

Files

Create

livery/info_receiver.pony — Public interface for sending messages to a connection:

interface tag InfoReceiver
  """
  A handle for sending messages to a LiveView connection.

  External actors use this to deliver messages that arrive via
  `LiveView.handle_info`. Obtain a reference by calling `Socket.self()`
  inside a lifecycle method.
  """
  be info(message: Any val)

Structural typing: _Connection satisfies this automatically by having the info behavior. No is InfoReceiver needed on _Connection.

livery/pub_sub.pony — Topic-based publish-subscribe actor:

use collections = "collections"

actor PubSub
  """
  Topic-based publish-subscribe for delivering messages to LiveView
  connections.

  Create a PubSub instance and pass it to `Listener`. LiveViews subscribe
  via `Socket.subscribe(topic)`. External actors publish via
  `pub_sub.publish(topic, message)`, which delivers to all subscribers
  via `InfoReceiver.info`.
  """
  // Backed by collections.HashMap[String, collections.SetIs[InfoReceiver tag],
  //   collections.HashEq[String]]

  new create()

  be subscribe(topic: String, subscriber: InfoReceiver tag)
    """Add a subscriber to a topic. Idempotent."""

  be unsubscribe(topic: String, subscriber: InfoReceiver tag)
    """Remove a subscriber from a topic."""

  be unsubscribe_all(subscriber: InfoReceiver tag)
    """Remove a subscriber from all topics. Called automatically by the
    connection actor when a WebSocket closes."""

  be publish(topic: String, message: Any val)
    """Send a message to all subscribers of a topic."""

Uses collections.SetIs[InfoReceiver tag] for identity-based comparison of actor references. unsubscribe_all does a linear scan of all topics — acceptable for typical topic counts.

examples/ticker/main.pony — Ticker-driven counter:

Imports: use "time", use "templates", use "json", use lori = "lori", use "../../livery".

A TickerView subscribes to a "tick" topic in mount. A Ticker actor publishes a message to the topic every second using Timers/Timer/TimerNotify. The view increments a counter in handle_info on each tick.

Demonstrates:

• handle_info receiving external messages
• PubSub subscribe/publish flow
• PubSub passed to both Listener and the external Ticker actor
• Auto-cleanup on disconnect (no explicit unsubscribe needed)

Modify

livery/live_view.pony — Add handle_info:

fun ref handle_info(message: Any val, socket: Socket ref) =>
  """
  Called when an external actor sends a message to this connection
  via PubSub or direct `InfoReceiver.info` calls.

  Default implementation does nothing. Override to handle server-push
  messages from timers, background jobs, or PubSub topics.
  """
  None

Default no-op on the trait. Existing LiveViews (like CounterView) don't need changes — they inherit the default.

livery/socket.pony — Add connection reference and PubSub methods:

New fields: _self: InfoReceiver tag, _pub_sub: PubSub tag

Updated constructor:

new create(assigns: Assigns ref,
  pending_events: Array[(String val, json.JsonValue)] ref,
  self': InfoReceiver tag,
  pub_sub: PubSub tag)

New methods:

fun box self(): InfoReceiver tag =>
  """
  Return a shareable reference to this connection.

  Pass this to external actors so they can send messages via
  `InfoReceiver.info`, which arrive at `LiveView.handle_info`.
  """

fun ref subscribe(topic: String) =>
  """
  Subscribe this connection to a PubSub topic. Messages published to
  the topic will arrive via `LiveView.handle_info`. Subscriptions are
  automatically cleaned up when the connection closes.
  """

fun ref unsubscribe(topic: String) =>
  """
  Unsubscribe this connection from a PubSub topic.
  """

subscribe calls _pub_sub.subscribe(topic, _self). unsubscribe calls _pub_sub.unsubscribe(topic, _self).

livery/_connection.pony — Add info behavior, PubSub integration, cleanup:

New field: let _pub_sub: PubSub tag

Updated constructor to accept and store pub_sub: PubSub tag. Pass this (as InfoReceiver tag) and pub_sub to the Socket constructor:

new create(auth: lori.TCPServerAuth, fd: U32,
  config: mare.WebSocketConfig val, routes: Routes val,
  pub_sub: PubSub tag)
=>
  _assigns = Assigns
  _pending_events = Array[(String val, json.JsonValue)]
  _pub_sub = pub_sub
  _socket = Socket(_assigns, _pending_events, this, _pub_sub)
  _router = routes
  _ws = mare.WebSocketServer(auth, fd, this, config)

In this constructor, this is _Connection ref (field initializers on the actor ensure all fields are defined before the constructor body runs, so this has ref capability). _Connection ref is passable as InfoReceiver tag because ref is a subtype of tag and _Connection structurally satisfies InfoReceiver via its info behavior.

New behavior:

be info(message: Any val) =>
  """Deliver an external message to the LiveView via handle_info."""
  match _view
  | let v: LiveView ref =>
    v.handle_info(message, _socket)
    _maybe_rerender(v)
  end

When _view is None (pre-mount), the message is silently dropped. This matches the existing on_text_message pattern.

Updated on_closed:

fun ref on_closed(close_status: mare.CloseStatus,
  close_reason: String val)
=>
  _pub_sub.unsubscribe_all(this)

Calls unsubscribe_all to clean up any PubSub subscriptions. No tracking needed — PubSub scans its own topic map.

livery/listener.pony — Accept PubSub parameter:

Updated constructor signature and field:

actor Listener is lori.TCPListenerActor
  // ... existing fields ...
  let _pub_sub: PubSub tag

  new create(auth: lori.TCPListenAuth, host: String, port: String,
    routes: Routes val, pub_sub: PubSub tag, out: OutStream tag)

Pass _pub_sub to _Connection in _on_accept:

fun ref _on_accept(fd: U32): _Connection =>
  _Connection(_server_auth, fd, _config, _routes, _pub_sub)

livery/livery.pony — Update package docstring to mention handle_info, PubSub, InfoReceiver, and Socket.self().

livery/_test.pony — New tests + updates:

New PubSub tests (async):

• _TestPubSubDeliver — subscribe then publish delivers to subscriber
• _TestPubSubNoSubscribers — publish to empty topic doesn't crash
• _TestPubSubUnsubscribe — unsubscribe stops delivery
• _TestPubSubUnsubscribeAll — removes subscriber from all topics
• _TestPubSubMultipleSubscribers — all subscribers on a topic receive

New Socket tests:

• _TestSocketSubscribeDeliver — create PubSub, create Socket with InfoReceiver, call socket.subscribe(topic), publish to topic, verify InfoReceiver receives the message. Tests the end-to-end wiring from Socket.subscribe through PubSub to InfoReceiver.info.

These use h.long_test() with test helper actors:

• actor \nodoc\ _TestInfoReceiver is InfoReceiver — receives messages, calls h.complete(true) on receipt
• actor \nodoc\ _DummyInfoReceiver is InfoReceiver — no-op receiver for tests that need a placeholder

For negative tests (verifying non-delivery after unsubscribe), use a two-subscriber pattern: subscribe both a "should not receive" receiver and a sentinel receiver, unsubscribe the first, publish, and have the sentinel verify delivery happened (proving publish was processed) while confirming the unsubscribed receiver got nothing.

Updated tests:

• _TestSocketPushEvent — update Socket constructor call to include _DummyInfoReceiver and a fresh PubSub as the new required parameters

Not tested in Phase 2:

_Connection.info behavior (the full path: info -> handle_info -> assigns change -> re-render -> send HTML) requires WebSocket client infrastructure to test. Same as Phase 1, connection actor integration tests are deferred until an end-to-end test harness exists. The PubSub and Socket tests verify the plumbing up to the InfoReceiver.info call; the internal _Connection dispatch follows the same _maybe_rerender path already used by on_text_message.

examples/counter/main.pony — Update Listener call to include PubSub:

Listener(lori.TCPListenAuth(env.root), "0.0.0.0", "8081",
  router.build(), PubSub, env.err)

The counter doesn't use PubSub, but the Listener API now requires it.

examples/README.md — Add ticker example description.

CLAUDE.md — Update to reflect Phase 2 changes:

• Public API section: add InfoReceiver, PubSub, Socket.self(), Socket.subscribe(topic), Socket.unsubscribe(topic), LiveView.handle_info
• Architecture / Internal section: note _Connection.info behavior and PubSub cleanup in on_closed
• File Layout: add info_receiver.pony, pub_sub.pony, examples/ticker/

No Changes

• livery/assigns.pony
• livery/factory.pony
• livery/router.pony
• livery/_wire_protocol.pony — No new wire messages (handle_info is server-side only)
• livery/_unreachable.pony

Architecture

Message Flow

External Actor ---publish(topic, msg)---> PubSub actor
                                            |
                                  for each subscriber:
                                            |
                                  subscriber.info(msg)
                                            |
                                            v
                                    _Connection actor
                                            |
                                  view.handle_info(msg, socket)
                                            |
                                  if assigns.changed():
                                    re-render + send HTML

Capabilities

• InfoReceiver is interface tag — shareable across actors, can only call behaviors
• PubSub is an actor — all external references are tag
• Socket stores InfoReceiver tag and PubSub tag as fields — both are sendable, safe within the ref class
• _Connection satisfies InfoReceiver structurally (has be info(message: Any val))
• In _Connection's constructor, this is ref (field initializers ensure all fields are defined). ref is a subtype of tag, so this is passable as InfoReceiver tag

Cleanup

When a WebSocket connection closes:

1. Mare fires on_closed on _Connection
2. _Connection calls _pub_sub.unsubscribe_all(this)
3. PubSub removes the subscriber from all topic sets
4. No dangling references — PubSub won't attempt to deliver to closed connections

Build and Test

make clean && make test ssl=openssl_3.0.x

What's Not in Phase 2

• JS client changes (no new wire messages; handle_info is server-side only)
• terminate lifecycle callback on LiveView (not needed with auto-cleanup; can be added later if users need custom disconnect logic)
• Distributed/persistent PubSub (the built-in PubSub is single-node, in-memory)
• Forms / lv-change / lv-submit (Phase 3)
• Server-rendered first paint (Phase 4)
• Components (Phase 5)
• Static/dynamic splitting (Phase 6)

[SeanTAllen]

Decision: Option A — Built-in PubSub within livery.

No plan to extract PubSub into a separate library. Pony's actor model handles inter-node communication natively, so a standalone PubSub library isn't needed. The simple PubSub actor lives in the livery package permanently.

[SeanTAllen]

Implemented in #7.

Deviations from the plan:

• The plan's Capabilities section incorrectly stated that this is ref when passed to Socket(...) in _Connection's constructor (claiming field initializers make all fields defined before the constructor body). In fact, this is tag at that point because _router and _ws are not yet assigned. The code is correct — InfoReceiver requires tag, and this as tag satisfies that. The explanation was wrong, not the code.
• Additional test helper actors (_SentinelInfoReceiver, _GuardedInfoReceiver, _CountingInfoReceiver, _ForwardingInfoReceiver) were added beyond what the plan named, to implement the negative test patterns the plan described.