Phase 1 Implementation Plan

[SeanTAllen]

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

Scope

Server-side Pony library only. The JS client (deliverable 7) lives in a separate repo per the design's scope section. Covers deliverables 1-6, 8-9.

Dependencies

Package	Locator	Version	use
mare	github.com/ponylang/mare.git	release-0.1.1	"mare"
templates	github.com/ponylang/templates.git	0.3.0	"templates"
json-ng	github.com/ponylang/json-ng.git	0.3.0	"json"

Files

Remove

• livery/main.pony — placeholder Main actor, incompatible with library package
• examples/basic/main.pony — placeholder, replaced by counter example

Create: Core Library (livery/)

livery.pony — Package docstring guiding users toward the LiveView trait and Socket API. Notes that HtmlTemplate (from templates library) is recommended for rendering.

live_view.pony — LiveView trait (Phase 1, no handle_info):

trait LiveView
  fun ref mount(socket: Socket ref)
  fun ref handle_event(event: String val, payload: JsonValue, socket: Socket ref)
  fun box render(assigns: Assigns box): String ?

• mount initializes assigns on the socket.
• handle_event responds to client interactions by updating assigns.
• render produces HTML from the current assigns. Partial — the framework handles errors gracefully (keeps the last successfully rendered HTML). box receiver because rendering should be a pure function of data.

assigns.pony — Assigns class backed by TemplateValues ref from the templates library:

• fun ref update(key: String, value: (String | TemplateValue)) — delegates to TemplateValues, sets dirty flag
• fun box apply(key: String): TemplateValue ? — delegates to TemplateValues
• fun box changed(): Bool — returns dirty flag
• fun ref clear_changes() — resets dirty flag
• fun box template_values(): TemplateValues box — returns backing store for use with HtmlTemplate.render()

Values are (String | TemplateValue) — the same types the templates library accepts. The backing TemplateValues handles wrapping plain strings automatically.

socket.pony — Socket class:

• Constructor takes Assigns ref and Array[(String val, JsonValue)] ref — shared references owned by _Connection
• fun ref assign(key: String, value: (String | TemplateValue)) — delegates to Assigns.update
• fun box get_assign(key: String): TemplateValue ? — delegates to Assigns.apply
• fun ref push_event(event: String val, payload: JsonValue) — appends to the shared pending events array, flushed by _Connection after render

factory.pony — Factory interface:

interface val Factory
  fun apply(): LiveView ref^ ?

Structural typing allows lambdas as factories: {(): LiveView ref^ ? => CounterView?}.

router.pony — Router ref builder + Routes val (immutable, shareable):

• Router.route(path: String, factory: Factory) — appends a route
• Router.build(): Routes val — freezes the route table by creating an iso Array and consuming it into Routes
• Routes has a package-private constructor (only callable from Router.build())
• Routes.apply(path: String): (Factory | None) — strips query string internally before matching, then does a linear scan lookup. O(n) is fine for typical route counts. Callers don't need to remember to strip query strings.

listener.pony — Listener actor:

• Implements TCPListenerActor (from lori, via mare)
• new create(auth: TCPListenAuth, host: String, port: String, routes: Routes val, out: OutStream)
• Creates WebSocketConfig(host, port) internally with sensible defaults for max message/handshake size
• Stores TCPServerAuth for passing to connection actors
• _on_accept(fd) creates _Connection with auth, fd, config, and routes
• _on_listen_failure() prints a message to out including the host and port so users know why the server didn't start

_connection.pony — _Connection actor:

• Implements WebSocketServerActor (from mare)
• Owns: _assigns: Assigns ref, _pending_events: Array[(String val, JsonValue)], _socket: Socket ref (wraps shared refs to assigns and pending events)
• Also owns: _ws: WebSocketServer, _view: (LiveView ref | None), _last_html: String val, _router: Routes val
• Two-phase init: _view = None initially. Mare's _on_accept fires before the HTTP upgrade handshake completes, so the URI isn't known yet.

Lifecycle:

1. on_open(request): Look up factory from router using request.uri (query string stripping is handled by Routes.apply), call factory in try block (sends error + closes on failure), call mount(_socket), render, send HTML, arm 60s idle timeout via lori
2. on_text_message(data): Decode JSON via _WireProtocol.decode_client_message(data), dispatch to handle_event or heartbeat ack
3. After handle_event: If _assigns.changed(), re-render (on failure: keep _last_html, send error to client), clear changes, flush pending push events
4. on_idle_timeout: Close WebSocket
5. on_closed: No-op in Phase 1 (no PubSub subscriptions to clean up)

_wire_protocol.pony — Wire protocol encode/decode:

• _WireProtocol primitive with static methods:
  • encode_render(html: String val): String val — {"t":"render","html":"..."}
  • encode_heartbeat_ack(): String val — {"t":"heartbeat_ack"}
  • encode_push_event(event: String val, payload: JsonValue): String val — {"t":"push","e":"...","p":...}
  • encode_error(reason: String val): String val — {"t":"error","reason":"..."}
  • decode_client_message(data: String val): (_ClientMessage | _WireError) — parses JSON, returns structured message or error
• _ClientMessage type alias: (_EventMessage | _HeartbeatMessage)
• _EventMessage class: let event: String val, let payload: JsonValue
• _HeartbeatMessage primitive (no fields — our protocol has no ref tracking)
• _WireError class: let reason: String val

_unreachable.pony — _Unreachable primitive for impossible else branches.

Create: Example

examples/counter/main.pony — Counter app from the design doc:

use "templates"
use "json"
use lori = "lori"
use "livery"

class CounterView is LiveView
  let _template: HtmlTemplate val

  new create() ? =>
    _template = HtmlTemplate.parse(
      """<div>
        <h1>Count: {{ count }}</h1>
        <button lv-click="increment">+</button>
        <button lv-click="decrement">-</button>
      </div>""")?

  fun ref mount(socket: Socket ref) =>
    socket.assign("count", "0")

  fun ref handle_event(event: String val, payload: JsonValue,
    socket: Socket ref)
  =>
    try
      let current = socket.get_assign("count")?.string()?.i64()?
      let next = match event
        | "increment" => current + 1
        | "decrement" => current - 1
        else current
        end
      socket.assign("count", next.string())
    end

  fun box render(assigns: Assigns box): String ? =>
    _template.render(assigns.template_values())?

actor Main
  new create(env: Env) =>
    let router = Router
    router.route("/counter", {(): LiveView ref^ ? => CounterView?})

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

examples/README.md — Brief description of the counter example.

Modify

corral.json — Add mare, templates, and json-ng as dependencies.

Shared-State Pattern

_Connection owns Assigns ref and Array[(String val, JsonValue)] ref. It passes refs to both into Socket's public constructor. When user code calls socket.assign(...), it mutates the shared Assigns. After the handler returns, _Connection checks _assigns.changed() directly. All refs stay within the same actor's isolation boundary — no capability issues.

Tests (livery/_test.pony)

Single test runner per project convention. All test types have \nodoc\ annotation.

Assigns Property Tests (PonyCheck)

1. Dirty tracking invariant: After N > 0 random update calls, changed() is true. After clear_changes(), changed() is false. One more update makes changed() true again.
2. Value roundtrip: update(key, value) then apply(key)?.string()? returns the original string.
3. Template bridge: template_values()(key)?.string()? matches what was assigned via update.

Wire Protocol Tests

1. Server encode: Verify encode_render produces valid JSON with correct "t" and "html" fields. Same for other encode functions.
2. Client decode valid: Construct event JSON string → decode → verify _EventMessage fields match.
3. Client decode heartbeat: Construct heartbeat JSON string → decode → verify _HeartbeatMessage.
4. Client decode invalid: Malformed JSON, missing "t" field, unknown message type → verify _WireError with descriptive reason.

Router Tests

1. Exact match returns the registered factory.
2. No match returns None.
3. Empty router returns None for any path.
4. Query string stripping: "/path?foo=bar" matches a route registered as "/path".

Socket Tests

1. push_event appends to the shared pending events array (verify array contents after call).

Not Tested in Phase 1

Connection actor integration tests require WebSocket client infrastructure (mare is server-only). These will be added when the JS client is available for end-to-end testing.

Build and Test

make clean && make test

What's Not in Phase 1

• JS client (separate repo)
• handle_info / PubSub (Phase 2)
• Forms / lv-change / lv-submit (Phase 3)
• Server-rendered first paint (Phase 4)
• Components (Phase 5)
• Static/dynamic splitting (Phase 6)

[SeanTAllen]

Implemented in #5.