Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (41 loc) · 2.85 KB

AGENTS.md

File metadata and controls

63 lines (41 loc) · 2.85 KB
Raw

Mare

A WebSocket server library for Pony, built on lori.

Contributing with an AI assistant

This is a Pony project. The ponylang org maintains a set of LLM coding skills. Get set up with them before contributing:

  • Not set up yet? Install them once:

    git clone https://github.com/ponylang/llm-skills.git
cd llm-skills
python install.py

  • Already set up? Make sure you're on the latest. If you installed with the script above, git pull in the directory where you cloned llm-skills and the symlinked skills update automatically — if you set them up another way, refresh them however that setup expects.

See the llm-skills README for details and other harnesses.

When you start working on this project, load the pony-skills skill — it tells your assistant which Pony skill to use for each task.

Read CONTRIBUTING.md.

Prose model

If you are running on an Anthropic model, use claude-opus-4-6 for writing comments, documentation, and other prose. Prose quality from Anthropic models dropped starting with Opus 4.7 and has gotten worse with each subsequent release.

Linting

Run make lint before considering any work done. Fix all issues it reports. make lint runs pony-lint, which checks for style and correctness problems in Pony source files. A clean lint run is part of "done" — don't open a PR or report completion with lint issues outstanding.

Building and testing

make test ssl=3.0.x                 # build + run tests + build examples
make unit-tests ssl=3.0.x           # tests only
make test-one t=TestName ssl=3.0.x  # run a single test by name
make examples ssl=3.0.x             # examples only

ssl= is required because mare uses ssl/crypto for the SHA-1 that computes the WebSocket handshake accept key. Set it to your installed TLS library: 4.0.x, 3.0.x, 1.1.x, or libressl.

Connection states

WebSocketServer — a class the handler actor owns — tracks the connection through four states. Every state handles every event, so the state machine shows which handler runs in each phase; the behavior itself lives in WebSocketServer.

_Handshaking → _Open → _Closing → _Closed
     │           │                   ↑
     └───────────┴───────────────────┘
        (handshake failure, error, or abnormal close)

A close-handshake timeout looks like a job for lori's idle timeout, but that resets on any TCP receive, so it cannot bound a close; the OS TCP timeout covers the degenerate case instead.

Conventions

  • Prefer qualified imports (use lori = "lori", use crypto = "ssl/crypto", and so on).
  • New test classes go in _test_*.pony files, registered in _test.pony.
  • \nodoc\ on test classes.