Metadata-Version: 2.4
Name: xcore-protocol
Version: 0.5.1
Summary: Canonical cross-service protocol for the XCore ecosystem
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: rfc3339-validator>=0.1.4
Requires-Dist: referencing>=0.35.0
Requires-Dist: PyYAML>=6.0.2
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"

# xcore-protocol

Canonical cross-service protocol for the XCore ecosystem.

## Mission
`xcore-protocol` is the canonical source of truth for XCore cross-service communication.

It defines:
- message schemas
- envelope structure
- route and stream metadata
- versioning and compatibility rules
- canonical fixtures
- generation inputs and tooling
- generated Java and Python protocol DTO/model artifacts
- thin handwritten validation and repository-tooling support around generated artifacts
- cross-language compatibility tests

## Scope
This repository contains only **cross-process / cross-service wire protocol artifacts**.

### In scope
- event, command, and RPC contracts
- envelope definitions
- route metadata
- shared payload subtypes
- protocol fixtures and validation helpers
- generation configuration and generated Java/Python protocol artifacts

### Out of scope
- application business logic
- Discord handlers or presentation code
- Mindustry runtime integration
- Mongo persistence
- app-specific reconnect/worker orchestration

## Repository Layout
- `docs/` — ADRs, architecture notes, policies, migration notes
- `spec/` — protocol specs, shared types, envelopes, routes, generation inputs
- `fixtures/` — valid, invalid, and legacy examples
- `generators/` — language generation config/templates/scripts
- `java/` — generated Java protocol artifacts for the canonical model surface
- `python/` — generated Python protocol package and thin helpers
- `compat/` — cross-language compatibility checks
- `scripts/` — validation and generation helper scripts

## Migrated Families

All planned message families are fully migrated and operational:

- **Moderation** — ban, mute, vote-kick, kick-banned, pardon, audit
- **Discord** — link-confirm, unlink, link-status, admin-access, link-code
- **Maps** — list request/response, remove request/response
- **Chat/Heartbeat** — chat messages, global chat, heartbeat, join/leave, server actions, player state commands
- **Telemetry** — Redis TTL snapshot payloads for Prometheus/Gateway telemetry aggregation

## Current Status

All canonical message families are defined with JSON Schema specs and canonical fixtures. Generated Java records (`org.xcore.protocol.generated.*`) and Python frozen dataclasses (`xcore_protocol.generated.*`) cover the supported generated protocol surface, including route-less telemetry snapshot payloads. `XCore-plugin` and `XCore-discord-bot` both consume generated artifacts as their sole transport model where applicable. Cross-language compatibility checks and full CI validation chain are in place.

## Releases

Each `vX.Y.Z` tag publishes the same version of both supported artifacts:

- Java: `org.xcore:xcore-protocol-java:X.Y.Z` from `https://maven.x-core.org/releases`
- Python: `xcore-protocol==X.Y.Z` from PyPI

Production consumers must use an exact released version. Git revisions and `-SNAPSHOT`
versions are only acceptable while developing the protocol itself. The release workflow validates
schemas, generated output, Java tests, Python tests, and distributable packages before publishing.

Before the first PyPI release, configure the `pypi` GitHub environment as a PyPI Trusted Publisher
for this repository's `Publish Release` workflow. No Python package registry is self-hosted.

## See Also
- `docs/adr/ADR-001-protocol-first.md`
- `docs/architecture/protocol-overview.md`
- `docs/policies/versioning.md`
- `docs/policies/compatibility.md`
