{"id":47621653,"url":"https://github.com/raskell-io/conflux","last_synced_at":"2026-04-01T22:17:21.877Z","repository":{"id":336514163,"uuid":"1150014153","full_name":"raskell-io/conflux","owner":"raskell-io","description":"Schema-aware config state coordination. Multiple writers, deterministic merge, git milestones.","archived":false,"fork":false,"pushed_at":"2026-03-05T14:49:25.000Z","size":352,"stargazers_count":3,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T18:11:37.338Z","etag":null,"topics":["gitops"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raskell-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["raskell-io"],"ko_fi":"raskell"}},"created_at":"2026-02-04T19:29:46.000Z","updated_at":"2026-03-05T14:52:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raskell-io/conflux","commit_stats":null,"previous_names":["raskell-io/conflux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/raskell-io/conflux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fconflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fconflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fconflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fconflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raskell-io","download_url":"https://codeload.github.com/raskell-io/conflux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fconflux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitops"],"created_at":"2026-04-01T22:17:21.132Z","updated_at":"2026-04-01T22:17:21.817Z","avatar_url":"https://github.com/raskell-io.png","language":"Rust","funding_links":["https://github.com/sponsors/raskell-io","https://ko-fi.com/raskell"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1 align=\"center\"\u003e\n  Conflux\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eSchema-aware config state coordination.\u003c/em\u003e\u003cbr\u003e\n  \u003cem\u003eMultiple writers, deterministic merge, git milestones.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.rust-lang.org/\"\u003e\n    \u003cimg alt=\"Rust\" src=\"https://img.shields.io/badge/Rust-stable-000000?logo=rust\u0026logoColor=white\u0026style=for-the-badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Apache--2.0-c6a0f6?style=for-the-badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/raskell-io/conflux/discussions\"\u003eDiscussions\u003c/a\u003e •\n  \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\nConflux is a daemon + CLI that replaces git as the write path for infrastructure config. Multiple actors — humans, CI pipelines, operators, autoscalers — submit typed operations through a schema-aware engine that merges them deterministically. Resolved state is periodically projected to a git repository as milestones.\n\n**The problem:** GitOps treats config files as source code. Multiple actors editing config race to push, create mechanical merge conflicts on structured data git doesn't understand, and diverge across long-lived environment branches. Git's text-level merge is the wrong primitive for typed config state.\n\n**The fix:** Move writes off git. Let a schema-aware engine handle concurrent modifications using per-field merge strategies (CRDT-backed). Project clean, auditable snapshots to git on your terms.\n\n## Status\n\nAll core crates implemented. Ready for early testing and feedback.\n\n## Quick Start\n\n```bash\n# Install\ncargo install conflux\n\n# Initialize a project\nconflux init --schema schema.toml\n\n# Import existing config files\nconflux import ./configs/ --entity-type service\n\n# Make a change\nconflux set route.api weight 80 --intent \"shifting traffic for canary\"\n\n# View entity state\nconflux get route.api\n\n# See document status\nconflux status\n\n# View operation history\nconflux log --limit 10\n\n# See who changed what\nconflux blame route.api\n\n# Create a milestone (commit to git)\nconflux milestone create -m \"post-canary traffic shift\"\n\n# Run the API server\nconflux daemon --port 8080\n```\n\n## How It Works\n\n```\n                    ┌─────────────────────────────────┐\n  Actors            │       Conflux Engine            │        Consumers\n                    │                                 │\n  Human (CLI/UI) ──\u003e│  ┌────────────────────────────┐ │──\u003e Git repo (milestones)\n  CI pipeline ─────\u003e│  │   CRDT Document Store      │ │──\u003e Webhook notifications\n  K8s operator ────\u003e│  │                            │ │──\u003e Pull API (reconcilers)\n  Autoscaler ──────\u003e│  │   Per-field merge logic    │ │──\u003e gRPC stream (watchers)\n  Policy engine ───\u003e│  │   Causal history (HLC)     │ │\n                    │  │   Schema + validation      │ │\n                    │  └────────────────────────────┘ │\n                    │                                 │\n                    │  ┌────────────┐ ┌─────────────┐ │\n                    │  │ Env/Stage  │ │  Milestone  │ │\n                    │  │ Overlays   │ │  Projector  │ │\n                    │  └────────────┘ └─────────────┘ │\n                    └─────────────────────────────────┘\n```\n\n1. **Actors submit typed operations** — `SetField(route.api-v1, weight, 80, actor=autoscaler)`, not a text diff\n2. **Schema defines merge rules** — Each field declares its merge strategy (last-writer-wins, max-wins, add-wins set, require-review)\n3. **Engine merges deterministically** — CRDT-backed, per-field, causal ordering via hybrid logical clocks\n4. **State is validated post-merge** — Schema constraints catch semantic errors that clean merges can't\n5. **Milestones project to git** — Periodic snapshots with structured commit messages and full causal attribution\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Schema-Aware Merge** | Per-field merge strategies: LWW, max, min, grow-set, OR-set, require-review |\n| **Multi-Actor** | Humans, CI pipelines, operators, autoscalers — all identified, all tracked |\n| **Causal Ordering** | Hybrid logical clocks for causally consistent, totally ordered operations |\n| **Environment Overlays** | Environments as a data dimension, not git branches. Promote with an operation, not a merge |\n| **Git Milestones** | Periodic snapshots to git with structured commit messages and operation attribution |\n| **Format Agnostic** | Import YAML, JSON, TOML, KDL, Jsonnet, CUE. Export to YAML, JSON, TOML, KDL, XML, HCL. Extensible via serializer plugins |\n| **Operation Log** | Append-only audit trail of every mutation with actor identity and intent |\n| **Post-Merge Validation** | Schema constraints enforced after every merge — convergence + correctness |\n| **API Key \u0026 mTLS Auth** | Secure API access with hashed API keys or client certificates |\n| **Role-Based Access Control** | Granular permissions per entity, field, and environment with role inheritance |\n| **Signed Operations** | Ed25519 digital signatures on operations for cryptographic auditability |\n| **Audit Export** | Export operation history as JSON Lines with signature verification |\n\n### Schema Example\n\nDefine your config structure and merge rules in TOML:\n\n```toml\nname = \"my-infrastructure\"\nversion = \"1.0.0\"\n\n[environments]\nbase = \"production\"\noverlays = [\n    { name = \"staging\", inherits = \"production\" },\n    { name = \"development\", inherits = \"staging\" },\n]\n\n[entity.route]\nfields = [\n    { name = \"path\",     type = \"string\",       merge = \"lww\" },\n    { name = \"weight\",   type = \"int\",          merge = \"max\" },\n    { name = \"timeout\",  type = \"duration\",     merge = \"min\" },\n    { name = \"service\",  type = \"ref\u003cservice\u003e\", merge = \"lww\" },\n]\n\n[entity.service]\nfields = [\n    { name = \"image\",    type = \"string\",     merge = \"lww\" },\n    { name = \"replicas\", type = \"int\",        merge = \"max\", default = 1 },\n    { name = \"env_vars\", type = \"map\",        merge = \"lww\" },\n    { name = \"ports\",    type = \"list\u003cint\u003e\",  merge = \"set\" },\n]\n```\n\n### Merge Strategies\n\n| Strategy | Semantics | CRDT Backing |\n|----------|-----------|--------------|\n| `lww` | Last writer wins (HLC + actor tiebreak) | LwwRegister |\n| `max` | Highest numeric value wins | MaxRegister |\n| `min` | Lowest numeric value wins | MinRegister |\n| `set` | Add and remove, concurrent add wins | ObservedRemoveSet |\n| `grow` | Elements can be added, never removed | GrowOnlySet |\n| `review` | Concurrent writes flagged for human review | ReviewRegister |\n\n### Milestone Commits\n\nGit history that humans actually want to read:\n\n```\nmilestone: post-canary traffic shift\n\nOperations since last milestone:\n  [autoscaler]  route.api-v1.weight: 50 → 90 (load-response)\n  [human:zara]  route.api-v1.weight: 90 → 80 (manual override)\n  [ci-pipeline] upstream.backend.targets: +10.0.1.5 (scale-out)\n\nEnvironments affected: production, staging\nCausal range: hlc:1706012400.0042 → hlc:1706015000.0187\nOperations: 3\n```\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `init` | Initialize a new Conflux project |\n| `import` | Import existing config files (YAML, JSON, TOML, KDL, Jsonnet, CUE) |\n| `set` | Set a field value on an entity |\n| `get` | Get entity or field values |\n| `diff` | Show changes since a milestone |\n| `log` | Show the operation log |\n| `blame` | Show per-field attribution (who changed what) |\n| `status` | Show document statistics |\n| `milestone` | Create, list, or show milestones |\n| `promote` | Promote configuration between environments |\n| `conflicts` | List unresolved conflicts |\n| `resolve` | Resolve a conflict by choosing a value |\n| `watch` | Watch for state changes in real-time |\n| `daemon` | Run the API server |\n| `auth` | Authentication management (hash API keys) |\n| `keys` | Cryptographic key management (generate, register, list, revoke) |\n| `rbac` | Role-based access control (list-roles, check, validate) |\n| `audit` | Audit log export and signature verification |\n\nSee [`crates/cli/docs/README.md`](crates/cli/docs/README.md) for full CLI documentation.\n\n### REST API\n\nThe daemon exposes a REST API for programmatic access:\n\n```bash\n# Get document state (with API key auth)\ncurl -H \"X-API-Key: your-api-key\" \\\n  http://localhost:9400/v1/state\n\n# Submit an operation\ncurl -X POST http://localhost:9400/v1/ops \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -d '{\n    \"type\": \"set_field\",\n    \"entity_id\": \"service.api\",\n    \"field\": \"replicas\",\n    \"value\": 5,\n    \"intent\": \"Scale for traffic\"\n  }'\n\n# Create a milestone\ncurl -X POST http://localhost:9400/v1/milestones \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -d '{\"message\": \"Deploy v2.0\", \"environments\": [\"production\"]}'\n\n# Export audit log\ncurl -H \"X-API-Key: your-api-key\" \\\n  \"http://localhost:9400/v1/audit/export?since=2024-01-01\"\n```\n\nSee [`crates/api/docs/README.md`](crates/api/docs/README.md) for full API documentation.\n\n### Security\n\nConflux provides enterprise-grade security features:\n\n**API Key Authentication**\n```bash\n# Generate an API key hash\nconflux auth hash-key \"your-secret-key\"\n# Output: sha256:2cf24dba5fb0a30e...\n\n# Add to .conflux/api-keys.toml\n# [[keys]]\n# key_hash = \"sha256:2cf24dba5fb0a30e...\"\n# actor_id = \"ci-pipeline\"\n# actor_class = \"pipeline\"\n```\n\n**Ed25519 Signed Operations**\n```bash\n# Generate a signing key pair\nconflux keys generate --actor alice --output ~/.conflux/keys/alice.pem\n\n# Register the public key\nconflux keys register --key-id alice@2024 --actor alice \\\n  --public-key \"M4kJ839WYm//Jarj9Xticyn6P7z1NQb+UAy5X6Y3dv8=\"\n```\n\n**Role-Based Access Control**\n```toml\n# rbac.toml\n[role.developer]\npermissions = [\n  { actions = [\"read\", \"write\"], resource = \"*@development\" },\n]\n\n[role.operator]\ninherits = [\"developer\"]\npermissions = [\n  { actions = [\"write\", \"override\"], resource = \"*@staging\" },\n  { actions = [\"promote\"], resource = \"*@production\" },\n]\n\n[[assignment]]\nactor_pattern = \"ci-*\"\nroles = [\"developer\"]\n```\n\n```bash\n# Check permissions\nconflux rbac check --actor alice --action write --resource \"service/api@staging\"\n```\n\n**Audit Export**\n```bash\n# Export operation history as JSON Lines\nconflux audit export --since 2024-01-01 --output audit.jsonl\n\n# Verify signatures in export\nconflux audit verify audit.jsonl --key-registry .conflux/keys.json\n```\n\n## Why Not Just Git?\n\nGit solves versioning. It doesn't solve collaboration on structured config:\n\n- **Merge conflicts on structured data** — Two people change different routes in the same YAML file, git panics\n- **Push races** — Whoever pushes first wins, everyone else rebases\n- **Branch drift** — Long-lived environment branches diverge structurally over months\n- **No actor identity** — `git blame` shows who committed, not who or what requested the change\n- **No intent tracking** — Commit messages are freeform text, not structured operation metadata\n- **Text-level merge** — Git doesn't know that a route and an upstream are independent entities\n\nConflux keeps everything people like about git (diffable history, auditable, inspectable) and removes everything that breaks (text merge, push races, branch-based environments).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCrates\u003c/strong\u003e\u003c/summary\u003e\n\nEach crate has its own `docs/` directory with detailed documentation.\n\n| Crate | Description |\n|-------|-------------|\n| [`conflux-core`](crates/core/) | CRDT document model, typed operations, per-field merge semantics, Ed25519 signing |\n| [`conflux-schema`](crates/schema/) | Schema definition language (TOML) for config structure and merge rules |\n| [`conflux-store`](crates/store/) | Pluggable storage backends (SQLite, PostgreSQL, DynamoDB) and audit export |\n| [`conflux-git`](crates/git/) | Git milestone projection, config format serialization, and serializer plugin API |\n| [`conflux-rbac`](crates/rbac/) | Role-based access control with inheritance and pattern matching |\n| [`conflux-api`](crates/api/) | HTTP and gRPC API server with authentication and authorization |\n| [`conflux`](crates/cli/) | CLI and daemon entry point |\n\n\u003c/details\u003e\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines.\n\n**Using Claude Code?** See [`.claude/CLAUDE.md`](.claude/CLAUDE.md) for project context, architecture, and coding rules.\n\n## Community\n\n- 💬 [Discussions](https://github.com/raskell-io/conflux/discussions) — Questions, ideas, show \u0026 tell\n- 🐛 [Issues](https://github.com/raskell-io/conflux/issues) — Bug reports and feature requests\n\n## License\n\nApache 2.0 — See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraskell-io%2Fconflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraskell-io%2Fconflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraskell-io%2Fconflux/lists"}