API and Protobuf Evolution

Current Phase

SyncTV is currently treated as a new project. Its own protobuf and API drafts may be reorganized freely while contracts are still being shaped. Field order, numbers, and message structure can be cleaned up without adding reserved entries for draft history.

Do not modify third-party vendored protobuf files such as:

• synctv-proto/proto/buf/validate/validate.proto
• Other vendored proto or code-generation dependency files

Caution

Protocol changes still need generated code, tests, examples, and docs updated together.

Protocol Surfaces

Surface	Main files or entry	Use
HTTP/OpenAPI	synctv-api/src/http/*, /api-docs/openapi.json	Web, mobile, third-party SDKs
gRPC	client.proto, admin.proto, provider proto	Strongly typed clients and debugging
Realtime WebSocket	ClientMessage, ServerMessage	Room chat, playback, WebRTC, resource observation
management gRPC	management proto and CLI	Operations control plane

Change Principles

Change	Current policy
New feature	Prefer clear messages, fields, errors, and permissions
Unclear field names	Rename and regenerate, updating all callers
Messy field numbers	Own proto can be renumbered without reserved
Unused fields	Remove after tests confirm no references
Third-party proto	Do not edit unless intentionally upgrading the dependency
Error codes	Keep range semantics clear and avoid duplicate codes

Protobuf Change Checklist

1. Confirm the file is SyncTV-owned, not third-party vendored proto.
2. Update .proto fields, numbers, comments, and RPCs.
3. Regenerate Rust code.
4. Update HTTP/gRPC/Realtime implementations and tests.
5. Update gRPC Debugging, Realtime API, or SDK and API Examples.
6. If client behavior changes, update Client Integration Guide and Errors.
7. Run proto, API, and docs checks.

HTTP API Change Checklist

1. Define auth, permissions, rate limit, body size, and error classification.
2. Update handler, OpenAPI annotations, and tests.
3. Start with the openapi feature and confirm Swagger UI and JSON generation.
4. Update examples, error handling, and client docs.
5. If room state changes, decide whether Realtime events or resource invalidation are required.

Realtime Changes

Realtime changes need special care:

• ClientMessage and ServerMessage oneof fields should be easy to dispatch.
• New observed resources need a version source, payload, trigger events, and delivery mode behavior.
• Reconnect semantics must state which observations are rebuilt and which versions can be reused.
• Avoid pushing large lists or binary data through frequent broadcast messages.

Documentation Sync

Change	Docs to update
Login, 2FA, OAuth2, token	Client integration, security model, errors
Rooms, permissions, members	Rooms and permissions, user guide, workflows
Playback, Provider, proxy	Playback model, Provider recipes
Realtime messages	Realtime API, SDK examples
Configuration field	Configuration index, full example, topic page
Operations behavior	Observability, troubleshooting, capacity, rotation

Continue Reading

• Development Environment
• OpenAPI Access
• gRPC Debugging
• Errors