From 5a80f2adca12942be9744f2dfb6b74dab8864382 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 28 Oct 2026 00:47:24 +0100 Subject: [PATCH] cultnet.error.v0: add code write_not_authorized across C#, both schema copies and Rust Captured-bytes case in cultnet-rs error_message.rs, asserted byte-for-byte by the C# schema contract test; the cultnet-distributed-database contract and the Networking README state the remote write authority invariant. Co-Authored-By: Claude Opus 5.5 --- contracts/cultnet/cultnet-distributed-database.md | 8 ++++++-- contracts/cultnet/cultnet.error.schema.json | 6 +++--- .../contracts/cultnet/cultnet.error.schema.json | 6 +++--- packages/cultnet-rs/src/contracts.rs | 3 +++ packages/cultnet-rs/tests/error_message.rs | 15 +++++++++++++++ src/GameCult.Networking/README.md | 5 ++++- .../CultNetSchemaContractTests.cs | 14 ++++++++++++++ 7 files changed, 48 insertions(+), 9 deletions(-) diff --git a/contracts/cultnet/cultnet-distributed-database.md b/contracts/cultnet/cultnet-distributed-database.md index 66bb450e..a170835e 100644 --- a/contracts/cultnet/cultnet-distributed-database.md +++ b/contracts/cultnet/cultnet-distributed-database.md @@ -111,8 +111,9 @@ Not implemented yet: not guess. Adding a code is therefore a coordinated change across every runtime, made together: the schema (both copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and a captured-bytes case in `packages/cultnet-rs/tests/error_message.rs` for it. TypeScript reads the schema. The current codes are -`selection_invalid`, `cursor_stale`, `cursor_invalid`, `reference_outside_target`, `variant_unsupported` and -`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns). +`selection_invalid`, `cursor_stale`, `cursor_invalid`, `reference_outside_target`, `variant_unsupported`, +`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns) and +`write_not_authorized` (a peer's put or delete its server's remote write authority did not grant). ## Live Invariants @@ -122,6 +123,9 @@ copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and - One primary owns writes for a shard until a stronger policy exists. - Non-owner writes are rejected or explicitly forwarded. They are not silently applied. +- A peer's put or delete is applied or forwarded only when the server's + `RemoteWriteAuthority` grants it; none configured refuses every remote write. + The connection key admits a peer to the transport and is never a grant. - Raw snapshot/put/delete messages must pass through `CultNetDatabase`, not bypass shard policy. - The accepted shard log is stored in replica catch-up wire form. Object logs diff --git a/contracts/cultnet/cultnet.error.schema.json b/contracts/cultnet/cultnet.error.schema.json index 59764338..e3b94c2b 100644 --- a/contracts/cultnet/cultnet.error.schema.json +++ b/contracts/cultnet/cultnet.error.schema.json @@ -28,7 +28,7 @@ "code": { "description": "Machine-readable refusal code (R-N). Additive: a v0 peer that does not know this field ignores it. The set is a closed enum: Rust and TypeScript refuse a message whose code is not listed, so adding a code is one coordinated change across every runtime (this schema, the C# factory, the Rust CultNetErrorCode, and a captured-bytes case for each).", "type": ["string", "null"], - "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema"] + "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema", "write_not_authorized"] }, "details": { "description": "Code-specific structured detail (R-N). Every field is populated only for the code that defines it; the others are null, not omitted.", @@ -36,8 +36,8 @@ "additionalProperties": false, "required": ["field", "value", "asOf", "current"], "properties": { - "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\".", "type": ["string", "null"] }, - "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns.", "type": ["string", "null"] }, + "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\".", "type": ["string", "null"] }, + "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns. write_not_authorized: the key of the refused write.", "type": ["string", "null"] }, "asOf": { "description": "cursor_stale: the cursor's own minted asOf.", "type": ["integer", "null"], "minimum": 0 }, "current": { "description": "cursor_stale: the answering server's current asOf.", "type": ["integer", "null"], "minimum": 0 } } diff --git a/packages/cultnet-rs/contracts/cultnet/cultnet.error.schema.json b/packages/cultnet-rs/contracts/cultnet/cultnet.error.schema.json index 59764338..e3b94c2b 100644 --- a/packages/cultnet-rs/contracts/cultnet/cultnet.error.schema.json +++ b/packages/cultnet-rs/contracts/cultnet/cultnet.error.schema.json @@ -28,7 +28,7 @@ "code": { "description": "Machine-readable refusal code (R-N). Additive: a v0 peer that does not know this field ignores it. The set is a closed enum: Rust and TypeScript refuse a message whose code is not listed, so adding a code is one coordinated change across every runtime (this schema, the C# factory, the Rust CultNetErrorCode, and a captured-bytes case for each).", "type": ["string", "null"], - "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema"] + "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema", "write_not_authorized"] }, "details": { "description": "Code-specific structured detail (R-N). Every field is populated only for the code that defines it; the others are null, not omitted.", @@ -36,8 +36,8 @@ "additionalProperties": false, "required": ["field", "value", "asOf", "current"], "properties": { - "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\".", "type": ["string", "null"] }, - "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns.", "type": ["string", "null"] }, + "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\".", "type": ["string", "null"] }, + "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns. write_not_authorized: the key of the refused write.", "type": ["string", "null"] }, "asOf": { "description": "cursor_stale: the cursor's own minted asOf.", "type": ["integer", "null"], "minimum": 0 }, "current": { "description": "cursor_stale: the answering server's current asOf.", "type": ["integer", "null"], "minimum": 0 } } diff --git a/packages/cultnet-rs/src/contracts.rs b/packages/cultnet-rs/src/contracts.rs index e4f67164..56afaa7c 100644 --- a/packages/cultnet-rs/src/contracts.rs +++ b/packages/cultnet-rs/src/contracts.rs @@ -246,6 +246,7 @@ pub enum CultNetErrorCode { ReferenceOutsideTarget, VariantUnsupported, UnownedSchema, + WriteNotAuthorized, } impl CultNetErrorCode { @@ -257,6 +258,7 @@ impl CultNetErrorCode { Self::ReferenceOutsideTarget => "reference_outside_target", Self::VariantUnsupported => "variant_unsupported", Self::UnownedSchema => "unowned_schema", + Self::WriteNotAuthorized => "write_not_authorized", } } @@ -268,6 +270,7 @@ impl CultNetErrorCode { "reference_outside_target" => Ok(Self::ReferenceOutsideTarget), "variant_unsupported" => Ok(Self::VariantUnsupported), "unowned_schema" => Ok(Self::UnownedSchema), + "write_not_authorized" => Ok(Self::WriteNotAuthorized), _ => Err(anyhow!("ErrorMessage.Code is not a recognized cultnet.error.v0 code")), } } diff --git a/packages/cultnet-rs/tests/error_message.rs b/packages/cultnet-rs/tests/error_message.rs index 5c633087..58732295 100644 --- a/packages/cultnet-rs/tests/error_message.rs +++ b/packages/cultnet-rs/tests/error_message.rs @@ -158,6 +158,21 @@ fn cases() -> Vec { }), }, }, + Case { + name: "write_not_authorized", + // C#: ForRemoteWriteRefused(new CultNetRemoteWriteRequest(null, Put, "some.schema.v1", new CultRecordKey("some:key"), null, null), "not granted") + csharp_hex: "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92177726974655F6E6F745F617574686F72697A65643A206E6F74206772616E746564AB726F7574696E6748696E74C0A4636F6465B477726974655F6E6F745F617574686F72697A6564A764657461696C7384A56669656C64A97265636F72644B6579A576616C7565A8736F6D653A6B6579A461734F66C0A763757272656E74C0", + message: || CultNetMessage::Error { + error: "write_not_authorized: not granted".to_string(), + code: Some(CultNetErrorCode::WriteNotAuthorized), + details: Some(CultNetErrorDetails { + field: Some("recordKey".to_string()), + value: Some("some:key".to_string()), + as_of: None, + current: None, + }), + }, + }, ] } diff --git a/src/GameCult.Networking/README.md b/src/GameCult.Networking/README.md index de8496d3..7347d145 100644 --- a/src/GameCult.Networking/README.md +++ b/src/GameCult.Networking/README.md @@ -197,7 +197,10 @@ reply. The first coherent shard policy is primary ownership. Each shard has one authoritative writer at a time. Clients may connect to any node; a non-owner node forwards a write to the owner or rejects it honestly when forwarding is -not available. Followers subscribe to committed shard mutations and apply them +not available. A node applies or forwards a peer's write only after its +`RemoteWriteAuthority` grants it; with none configured it refuses all of them, and a +write forwarded to a primary is judged again there for the forwarder's connection. +Followers subscribe to committed shard mutations and apply them through the same CultCache reconciliation path as local file changes. This should feel like the local-first parts of Firebase or RethinkDB without diff --git a/tests/GameCult.Networking.Tests/CultNetSchemaContractTests.cs b/tests/GameCult.Networking.Tests/CultNetSchemaContractTests.cs index 3aa2705d..8b989bb6 100644 --- a/tests/GameCult.Networking.Tests/CultNetSchemaContractTests.cs +++ b/tests/GameCult.Networking.Tests/CultNetSchemaContractTests.cs @@ -206,6 +206,20 @@ namespace GameCult.Networking.Tests AssertErrorMatchesSchema(message); } + [Test] + public void ErrorMessage_RemoteWriteRefusedRealBytes_MatchesItsSchema() + { + var request = new CultNetRemoteWriteRequest(null!, CultNetRemoteWriteOperation.Put, "some.schema.v1", new CultRecordKey("some:key"), null, null); + var message = CultNetErrorMessage.ForRemoteWriteRefused(request, "not granted"); + + Assert.That(message.Code, Is.EqualTo("write_not_authorized")); + Assert.That(message.Details!.Field, Is.EqualTo("recordKey")); + Assert.That(message.Details.Value, Is.EqualTo("some:key")); + AssertErrorMatchesSchema(message); + // The bytes cultnet-rs's error_message.rs write_not_authorized case decodes and re-encodes. + Assert.That(Convert.ToHexString(CultNetSchemaMessageSerialization.Serialize(message)), Is.EqualTo("85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92177726974655F6E6F745F617574686F72697A65643A206E6F74206772616E746564AB726F7574696E6748696E74C0A4636F6465B477726974655F6E6F745F617574686F72697A6564A764657461696C7384A56669656C64A97265636F72644B6579A576616C7565A8736F6D653A6B6579A461734F66C0A763757272656E74C0")); + } + private static void AssertErrorMatchesSchema(CultNetErrorMessage message) { var validator = new MiniJsonSchemaValidator(SchemaDir());