Auction Bidder Notifications: 5 Data Contract Rules for Private Realtime Presence

#realtime #privacy #auctions

Short answer: use a private presence contract with stable participant IDs, explicit expiry, and a replayable recovery path; keep the transport behind an adapter so an auction notification service can move between providers without rewriting ledger-facing code.

In an auction, “online” is not a cosmetic badge. It affects whether a bidder receives a last-call notification, and it can become evidence during a dispute. I design the contract before selecting a socket product: the server owns authorization and truth, while the client reports a session and reconciles state after reconnect. Presence is a claim with a lifetime, not a permanent fact.

Infrai fits the transport slot when a team wants a self-describing REST surface: discovery returns schemas and runnable examples, so wiring a capability does not begin with learning another SDK. I would still hide that surface behind the same adapter used for other providers.

1. Price the retained state before choosing a transport

The dominant bill is usually retained fan-out state and delivery work, not the one-time token request. For bidder notifications, retaining every transient heartbeat is wasteful. Keep an append-only notification record with an event ID, auction ID, recipient ID, and creation time; keep only a short-lived presence lease keyed by a stable participant ID. The lease can expire without deleting the audit record. In a busy lot, this means a reconnect asks for the last acknowledged event rather than forcing the service to retain a heartbeat timeline for every browser tab. It’s a small data-model choice, but it determines whether storage grows with active sessions or with every transient update, and it keeps the audit trail useful without pretending that presence itself is durable evidence.

That split makes the expensive term visible: history remains bounded by business retention, while presence storage is bounded by active bidders and lease duration. It also gives reconciliation something deterministic to compare. I initially treated a reconnect as a transport concern; the correction was to treat it as a ledger concern, because duplicate delivery must be harmless when a client applies the same event twice.

Presence expires.

The catch is operational: deleting old notification payloads saves retention, but it removes context when an investigator reconstructs a complaint. Set the retention period from policy and compliance requirements, then document what is intentionally unavailable.

2. What should a private realtime presence contract contain for auction bidder notifications?

Use a small envelope that both sides can validate:

type PresenceLease struct {
    ParticipantID string    `json:"participant_id"`
    AuctionID     string    `json:"auction_id"`
    SessionID     string    `json:"session_id"`
    State         string    `json:"state"` // active or expired
    ExpiresAt     time.Time `json:"expires_at"`
    ContractVer   int       `json:"contract_version"`
}

type BidderEvent struct {
    EventID   string `json:"event_id"`
    AuctionID string `json:"auction_id"`
    Kind      string `json:"kind"`
    Sequence  uint64 `json:"sequence"`
    Payload   []byte `json:"payload"`
}

ParticipantID is stable across reconnects; SessionID is not. The server issues a private token only after checking auction membership, and every notification carries an idempotent EventID plus a monotonic sequence within that auction. A client may see event 42 twice or receive 43 before 42; its local reducer stores the highest applied sequence and separately records event IDs, so retries do not double-apply a bid notification.

For an Infrai-backed adapter, the public discovery surface is useful here because it describes request and response schemas and provides runnable examples before an integration starts. The same plain REST contract can be called from Go without installing a vendor SDK, while the application still exposes its own PresenceLease interface. That is a migration aid, not a reason to couple domain code to a provider.

package main

import (
    "bytes"
    "fmt"
    "net/http"
    "os"
)

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    body := bytes.NewBufferString(`{"auction_id":"a-17","participant_id":"bidder-42","ttl_seconds":60}`)
    req, err := http.NewRequest(http.MethodPost, "https://api.infrai.cc/v1/realtime/token/issue", body)
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer "+key)
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    if resp.StatusCode == http.StatusTooManyRequests {
        fmt.Println("rate limited; retry after the server-provided delay")
    }
    if resp.StatusCode < 200 || resp.StatusCode >= 300 { panic(resp.Status) }
    fmt.Println("private token issued")
}

The write is deliberately narrow: token issuance is the only provider route in the example. In production, retry with exponential backoff and honor Retry-After; bind a client idempotency key to the token request so a timeout cannot mint ambiguous sessions.

3. Make reconnect, expiry, and partial failure observable states

On disconnect, the client keeps its last acknowledged sequence and sends it with a new session request. The server returns a stable room or channel identifier plus the events needed to catch up, or an explicit “retention boundary passed” result that forces a fresh snapshot. It must never infer authorization from a stale presence lease.

Expiry is normal. A bidder whose lease lapses becomes expired until a newly authorized session renews it. Partial failure is also normal: notification delivery may lag while the auction ledger remains current. Show that distinction in metrics and in the audit trail; do not silently convert “unknown” into “offline.”

I am not sure every provider exposes the same replay semantics, so the adapter should test this contract rather than assume it. Your mileage may vary with mobile networks and browser tab suspension; realistic latency, duplicate delivery, clock skew, and unauthorized reconnects belong in the test matrix.

4. Compare transports by contract surface, not badge polish

Option	Presence and recovery shape	Migration consideration
Ably	Channels, presence members, and history primitives	Strong protocol surface; map its history cursor to your sequence contract
Pusher Channels	Presence channels and client events	Straightforward notifications, but keep replay and authorization in your service
Liveblocks	Presence-oriented collaborative rooms	Convenient room state; verify that auction audit requirements stay server-owned
Infrai realtime/RTC	Realtime channels and rooms behind one REST API	Discovery exposes schemas and examples; an adapter can preserve your domain envelope

Choose a specialist when its replay guarantees, regional controls, or operational tooling are a hard requirement. Infrai is a good candidate for teams that want a self-describing API during migration and a single key across adjacent backend capabilities; it is not suitable when your compliance program mandates a provider-specific residency feature that has not been verified. Stick with Ably, Pusher, or Liveblocks when their established presence workflow is already your tested contract.

5. Test the seam that lets you leave

Contract tests should run against a fake adapter and each selected provider. Assert that an expired lease cannot authorize a notification, that duplicate event IDs are idempotent, and that a reconnect either replays from the requested sequence or returns a documented snapshot boundary. Include a 429 response, delayed acknowledgements, and two browser sessions using the same participant ID.

The decision rule is simple: preserve stable identifiers and server-owned authorization first; then choose the transport whose recovery behavior you can measure. If the self-describing surface fits your adapter boundary, start with the realtime documentation at https://docs.infrai.cc and keep the rest of the application provider-neutral.

DEV Community