chatto-api-rules
Design rules concerning Chatto's ConnectRPC API, both resources and realtime
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 3.0k
- Forks
- 152
01 前言 Front Matter
- name
- chatto-api-rules
- description
- Design rules concerning Chatto's ConnectRPC API, both resources and realtime
03 SKILL.md 正文
ConnectRPC Resource API
- Define one canonical public protobuf for each resource. Reuse that protobuf across list, get, batch, and mutation-response surfaces when the authorization and lifecycle semantics are the same.
- Keep services complete for their resource and scope. Add bounded batch reads when events or related resources commonly expose IDs that clients must hydrate.
- Keep commands, explicit reads, pagination, history, and read-your-writes responses in ConnectRPC. Realtime delivery does not replace these APIs.
- Resource
Update*RPCs must usegoogle.protobuf.FieldMask update_mask. Unselected fields stay unchanged; selected fields can be set or cleared, subject to validation. Apply masks before validation. Omitted masks infer populated fields; explicit empty masks are invalid. Clients should send explicit paths. Commands use specific verbs such asSet,Change, orRefresh.
Realtime API
- Cover the complete useful product event surface for integrations, bots, and clients. Do not limit the public event catalogue to events used by the bundled frontend.
- Use
chatto.core.evt.v1.Eventfor durable EVT facts andchatto.core.pubsub.v1.PubSubEventfor transient NATS Core signals. Use the dedicatedchatto.realtime.v1.RealtimeEventunion and domain payload catalog for public delivery. Keep a semantic one-to-one relationship for selected public events without importing core payload types into the public schema. Client-facingPubSubEventvariants should reference public payload types directly. Keep the restricted private union as the allow-list for cursorless delivery. - Keep transport concerns in
chatto.realtime.v1wrappers. Handshakes, subscriptions, catch-up, cursors, heartbeats, errors, and close guidance are not domain events. - Create a fresh authorized
RealtimeEventfor each public delivery. The public payload schema must omit internal variants and storage-only fields. Never send stored bytes or mutate a stored event during mapping. - Keep current resources in ConnectRPC. Let a resource client bind reads to an opaque realtime start cursor, then close the interval with event catch-up. Do not attach resource sidecars to normal event frames.
- Keep public cursors opaque, confidential, integrity-protected, and bound to their viewer and scope. Do not expose NATS or JetStream coordinates.
- Keep wire volume bounded. Resume must have sequence, event-count, time, and concurrency limits. Large and lazy collections stay in paginated ConnectRPC APIs.
- Use consistent product terminology and names. Public comments must not depend on backend terms such as projections, NATS, or JetStream.
- Use a new behavioral protocol version when a change requires all clients to change their behavior. Do not use a capability matrix to restate required frame semantics.
- When an
EventorPubSubEventvariant must reach clients, update the dedicated payload, public union member, authorization and mapper coverage, consuming reducers, generated clients, architecture inventory, public documentation, and compatibility notes in the same change. Keep public names and compact union numbers independent from the internal event source. Use independent public payload field numbers and explicit typed mapping for EVT. Reference the public payload directly from client-facing pubsub variants and deep-copy it at the delivery boundary. - Keep protobuf comments, public API overviews, tutorials, compatibility guidance, and release notes current.
04 同仓库更多 Skills
chatto-release-checklist
Check Chatto release readiness, including release metadata, upgrade guidance, and docs website consistency. Use when preparing or reviewing a Chatto release or release PR.
github
Work with GitHub issues, pull requests, and repository information for Chatto. Use for issue searches, bug reports, feature requests, issue updates, and GitHub access checks.
writing-tests
Instructions and hints for writing tests.
update-project-dependencies
Update Chatto Go and frontend dependencies within their compatible version ranges, then run tests.
svelte-docs
Look up official Svelte, SvelteKit, and Svelte CLI documentation.
svelte-core-bestpractices
Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more.