Per-URL OG metadata replicated as protocol events, deterministic shortcodes, gateway-side meta injection for crawlers, and three-event lifecycle (UPSERT / EXTEND / TEARDOWN).
Crawlers and chat unfurlers do not run JavaScript. The marketplace is a Next.js single-page application where listings, collections, and profiles are rendered client-side from API responses — which means a vanilla request to /listings/<id> returns the same skeleton HTML regardless of the asset. Without a server-side metadata layer, every shared link would unfurl into the same generic title and image.
The SSR system fixes this by emitting per-URL metadata as signed protocol events, replicating that metadata to every node, and injecting it into the skeleton HTML at the gateway edge for crawler requests.
ssrPaths TableEach entry in ssrPaths represents one renderable URL plus the metadata that should appear when a crawler hits it:
| Column | Purpose |
|---|---|
path | The canonical URL path (primary key) |
shortcode | Deterministic shortcode for /s/<code> redirects |
ssrType | Domain tag (LISTING, COLLECTION, PROFILE, etc.) for routing render templates |
meta | JSONB blob containing title, description, OG image, structured data |
state | ACTIVE / GONE / EXPIRED |
teardownReason / goneUntil | Soft-delete state with optional revival timer |
expiresAt | When the path naturally expires (listing TTL, etc.) |
version | Monotonic counter so out-of-order events are resolved deterministically |
lastEventHash | Hash of the protocol event that produced the current row |
The path itself is the primary key — there is exactly one row per URL.
SSR state propagates via three Ed25519-signed protocol events, gossiped network-wide like any other event:
| Event | When It Fires | Effect |
|---|---|---|
SSR_PATH_UPSERT | New URL becomes renderable, or its metadata changes | Inserts/updates the ssrPaths row and assigns/keeps the shortcode |
SSR_PATH_EXTEND | An existing path's lifetime needs extension (e.g. listing renewed) | Pushes expiresAt forward without rewriting the metadata |
SSR_PATH_TEARDOWN | Path is no longer valid (listing sold/cancelled, profile deleted) | Marks state GONE with a reason and an optional grace window |
Each event carries the path, a monotonic version, and an emittedAt timestamp. The version field means that even if events arrive out of order across the gossip mesh, every node converges on the same final state — the latest version always wins.
Every SSR path gets a shortcode derived from the path itself via the protocol-shared shortcodeForPath helper. Because the function is deterministic, every node independently arrives at the same code for the same path without any coordination. /s/<code> lookups resolve to the canonical URL, and click counts are tracked per-shortcode in ssrShortlinks.
A separate ssrShortlinks table holds optional vanity codes owned by a profile. These are the user-created custom slugs ("/s/my-drop") that point at an existing ssrPaths row, with optional metadata overrides. Auto-generated codes live on the ssrPaths row directly; vanity codes are layered on top.
The Rust gateway is the only actor that sees crawler requests directly. When a request arrives:
ssrPaths cache<head> (title, description, OG tags, structured data, canonical URL)/_og/:asset), the gateway returns a content-hashed pre-rendered imageReal users never see this path — they get the normal SPA shell and hydrate against the API. Only crawlers receive the injected meta.
Open Graph images are rendered server-side using resvg (a Rust SVG → PNG renderer). The flow:
/_og/:hash.pngContent hashing means image cache invalidation is automatic — change the underlying metadata, the hash changes, the gateway serves the new image.
A naive design would have nodes ask each other for SSR metadata over HTTP at request time. That couples crawler latency to peer reachability and introduces a coordination point. Treating SSR state as a first-class protocol event means: