pondsocket-common

Shared wire types, schemas, and reactive primitives consumed by both pondsocket (server) and (eventually) pondsocket-client (Python client). Mirrors the role of @eleven-am/pondsocket-common in the JavaScript monorepo.

This package has one runtime dependency: pydantic v2.

Install

pip install pondsocket-common

In a workspace it's installed automatically via uv sync.

What's in it

Wire format

Outbound client → server (ClientMessage):

{
  "action": "BROADCAST",
  "event": "message",
  "channelName": "/chat/42",
  "requestId": "<uuid>",
  "payload": {"text": "hi"}
}

Server → client (ServerMessage | PresenceMessage) discriminated on action:

{ "action": "SYSTEM",  "event": "ACKNOWLEDGE", "channelName": "/chat/42", "requestId": "...", "payload": {} }
{ "action": "PRESENCE", "event": "JOIN",       "channelName": "/chat/42", "requestId": "...", "payload": {"presence": [...], "changed": {...}} }

Field names on the wire are camelCase. The Python models use snake_case attributes (request_id, channel_name) with pydantic aliases. Use model_dump(by_alias=True) to serialize to wire form.

Parity with @eleven-am/pondsocket-common

• Enums have identical string values.
• Subject/BehaviorSubject mirror the JS classes 1:1 (synchronous fan-out, size property, close() semantics, BehaviorSubject initial-value replay on subscribe).
• ValidationError(message, path?) formats as "path: message" to match.
• uuid() returns a dashed lowercase hex string (matches crypto.randomUUID()).

The pydantic models are the canonical schema definitions on the Python side; the JS package uses hand-rolled validators with the same field-name shape.

License

GPL-3.0-or-later.