Metadata-Version: 2.4
Name: pygar_client
Version: 4.24.0
Summary: A Python client for the GAR protocol
Home-page: https://www.trinityriversystems.com/docs/gar_protocol/
Author: Jon Hill
Description-Content-Type: text/markdown
Requires-Dist: websockets>=13
Requires-Dist: msgspec>=0.18
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

---
top_level: true
description: The GAR WebSocket protocol — what a session is and how its parts fit, with links to the pages on the connection and handshake, record updates and batches, conditional and failed writes, synchronization signals, termination, and subscriptions.
---

# Generic Active Records Protocol Documentation

The wire protocol every GAR client and server speaks: the handshake, subscriptions and their
filters, the binary and JSON encodings, batching, ownership, failed writes and termination.

## Overview

The GAR protocol is a WebSocket-based messaging system built on top of TCP. It is used for streaming and snapshot-style data delivery and operates over a single bi-directional socket connection. When establishing a connection, clients must specify the subprotocol `"gar-protocol"`:

```
Sec-WebSocket-Protocol: gar-protocol
```

## How the pages fit

A session opens with an Introduction, then carries subscriptions one way and record writes both
ways until it ends; each page below covers one part of that.

- [Connection and session](protocol_session.md) — the connection itself: encodings, framing, the introduction, identity and heartbeats.
- [Record updates, batches and key teardown](protocol_record_updates.md) — the messages that carry records, their stamps and diagnostics, batches and key teardown.
- [Compare-exchange, writer ownership and failed writes](protocol_writes.md) — conditional writes, the ownership marker, and what comes back when a write fails.
- [Echo, subscription status and synchronizing without sleep](protocol_synchronization.md) — the signals a client waits on: echo, subscription status, server readiness.
- [Termination and starting again](protocol_termination.md) — how a session ends, what the client is told, and restarting it.
- [Subscriptions](subscriptions.md) — the subscribe request: snapshot versus streaming, filters, exclusions, joins, queries and the nagle interval.

## Subscriptions

A subscription names the classes, keys and topics a client wants and whether it is a one-shot snapshot or streaming; filters, the referencing-class list, exclusions, the class join and the nagle interval are all fields of it. The full reference is [Subscriptions](subscriptions.md).

## Auditing Topics (Control Port)

When running in audit mode (`--ws-control-port <port>`), GAR will emit internal topic traffic for monitoring

## g Schema

 - [g.psi](../../website/docs/g.psi)

## Protocol Schema

- [proto.psi](../../website/docs/g/proto.psi)

## Related

- [af_unix_transport.md](../../website/docs/af_unix_transport.md) — local connections silently use AF_UNIX sockets
  rather than TCP loopback, and why a URL may resolve to `unix:`.
- [gar_pipelining.md](../../website/docs/gar_pipelining.md) — streaming records between endpoints in a shell pipeline,
  and the failure modes to watch for.

## Deployment Schema

- [deployment.psi](../../website/docs/g/deployment.psi)

## Features in this area

- [client libraries](../../features/client_libraries/client_libraries.md) — Connecting to GAR from Python (pygar) and JavaScript (jsgar) over WebSocket.
- [subscription class join](../../features/subscription_class_join/subscription_class_join.md) — Joining a subscription's key filter against another class's key set.
- [subscription query](../../features/subscription_query/subscription_query.md) — Admitting a subscription's keys by what their records say: a schema-declared predicate with typed arguments, live membership, and where a proxy evaluates it.
- [key name list subscription](../../features/key_name_list_subscription/key_name_list_subscription.md) — Making a subscription with a finite list of key names snapshot by direct lookup instead of scanning the class.
- [rpc](../../features/rpc/rpc.md) — Calling a named GAR function and getting a structured reply.

## Internals
<!-- private -->

The implementation record — every private section this page used to carry — is [protocol_internals.md](protocol_internals.md).
