Merge pull request #684 from openpacketcore/feat/663-restore-ledger-ig4xo5fa

fix(session-store): enforce protected payload limits

Author: VerifiedOrganic

.github/workflows/ci.yml

@@ -357,6 +357,15 @@ jobs:
       - name: Run opc-gtpu-dataplane unit tests on macOS
         run: cargo test --locked -p opc-gtpu-dataplane --lib
 
+      # Dynamic and fixed durable consensus deliberately rely on Linux
+      # descriptor-pinned SQLite snapshot handling. This native lane proves
+      # the public and core constructors fail closed before durable setup.
+      - name: Prove unsupported consensus initialization is side-effect free on macOS
+        run: cargo test --locked -p opc-session-store --all-features unsupported_platform_before_durable_initialization
+
+      - name: Lint opc-session-store on macOS
+        run: cargo clippy --locked -p opc-session-store --all-targets --all-features -- -D warnings
+
   rust:
     name: Rust workspace
     runs-on: ubuntu-latest

crates/opc-session-net/README.md

@@ -313,14 +313,21 @@ mutation or rebuild authority beside Openraft.
   scope, cursor shape, and the server's claimed progress; it cannot prove that
   an authenticated server did not omit records or falsely report completion.
   Production completeness is the local Openraft-applied scan after a
-  linearizable barrier, not this compatibility RPC. Backends may return fewer records than requested
-  (including an empty advancing sparse page) to stay within the fixed 4 MiB
-  payload, 8 MiB retained-page, 8 MiB examined-metadata, and 4,096
-  examined-candidate budgets; callers continue from the
-  confidential authenticated `next_cursor` until `complete`. A server does not
-  rewrite a backend cursor to fit a smaller wire frame: it returns
-  `RestoreScanResponseTooLarge`, allowing the caller to retry from the same
-  cursor with a smaller record limit. The wire omits redundant `loaded_count`
+  linearizable barrier, not this compatibility RPC. The server conservatively
+  narrows the dispatched record limit from the effective negotiated response
+  frame using the `effective_max / 8192` record-count heuristic (with a
+  minimum of one); it does not derive that count from the fixed 2,096,128-byte
+  wire-payload cap. Backends may independently return fewer records than that
+  narrowed request (including an empty advancing sparse page) to stay within
+  their retained-page, aggregate-payload, examined-metadata, and 4,096
+  examined-candidate budgets; callers continue from the confidential
+  authenticated `next_cursor` until `complete`. The transport validates the
+  entire backend page against the fixed wire-payload cap and effective frame;
+  it never trims or rewrites records or the cursor. An oversize page returns
+  `RestoreScanResponseTooLarge` when that error is representable, or closes
+  the connection. The SDK does not automatically retry or change the request
+  limit; a caller may retry the same cursor with a smaller record limit. The
+  wire omits redundant `loaded_count`
   and `complete` values and recomputes both from records and cursor.
 - `SessionBackend::probe_replication_head` performs a fresh, deadline-bounded
   wire request. It does not consult the client's capability cache and reports
@@ -337,7 +344,7 @@ mutation or rebuild authority beside Openraft.
   `MAX_REPLICATION_OPERATIONS_PER_ENTRY` (256). The root is depth 1 and every
   operation node, including `Batch`, counts toward the per-entry total.
 - Independent protocol work limits admit at most 256 batch operations, 1,024
-  restore records and 4 MiB of restore payload, 65,536 replication-log
+  restore records and 2,096,128 bytes of restore payload, 65,536 replication-log
   entries, and 65,536 rebuild entries.
   These limits apply in addition to the configured encoded-frame bound.
 - Every post-bootstrap server response and watch item is fully bounded-encoded
@@ -357,7 +364,8 @@ mutation or rebuild authority beside Openraft.
   also enforces the finite 365-day horizon; production OpenRaft binds it to the
   leader-authored command time, never the client's or follower's wall clock.
 - If one record cannot fit, the call returns
-  `StoreError::RestoreScanResponseTooLarge` instead of retrying indefinitely.
+  `StoreError::RestoreScanResponseTooLarge`; the SDK does not automatically
+  retry it.
 - `listen(bind_addr).await` starts the listener and returns a server handle and
   bound address.
 - `ServerHandle::abort()` schedules non-blocking listener/connection
@@ -397,13 +405,14 @@ build.
 
 ### Outbound response contract
 
-Protocol v5 contract-profile wire-schema revision 6 retains revision 5's
-confidential authenticated snapshot-bound
-restore cursor, explicit durable-page profile, fixed 4 MiB restore payload and
-8 MiB retained-page, 8 MiB examined-metadata, and 4,096 examined-candidate
-budgets and exact configuration/process epoch binding for direct CAS. Revision
-5 adds the bounded, payload-free `RecordExpiryPreflight` authority exchange.
-Revision 6 adds the fixed `ConnectionRetiring` no-dispatch proof used for safe
+Protocol v5 contract-profile wire-schema revision 7 retains revision 6's
+confidential authenticated snapshot-bound restore cursor, explicit
+durable-page profile, 8 MiB retained-page, 8 MiB examined-metadata, and 4,096
+examined-candidate budgets and exact configuration/process epoch binding for
+direct CAS. Revision 7 corrects the restore payload fence from a nominal 4 MiB
+that worst-case JSON could not carry to the frame-safe 2,096,128-byte budget.
+Revision 5 adds the bounded, payload-free `RecordExpiryPreflight` authority
+exchange. Revision 6 adds the fixed `ConnectionRetiring` no-dispatch proof used for safe
 reconnection during authentication-material rotation. When lifecycle
 retirement is observed after mutual TLS and before any `HelloAck` bytes are
 written, the server returns the same complete control as
@@ -419,7 +428,7 @@ handshake. `requested_response_frame_size`,
 `Option<u32>` bootstrap fields so an older decoder can classify an otherwise
 decodable legacy minimal bootstrap. This is not bidirectional mismatch
 negotiation: an older decoder may reject unknown fields by simply closing.
-Exact revision-6 v5 admission requires each to be `Some`, at least
+Exact revision-7 v5 admission requires each to be `Some`, at least
 `MIN_NEGOTIATED_FRAME_SIZE` (8 KiB, or 8,192 bytes), and at most
 `MAX_NEGOTIATED_FRAME_SIZE` (16 MiB, or 16,777,216 bytes). The profile pins
 both as `min_frame_size = 8192` and `max_frame_size = 16777216`.
@@ -428,8 +437,18 @@ second independently configurable limit. The accepted response size is the
 smaller of the client's receive limit and the server's configured frame limit;
 the server request size independently bounds frames sent by that client. This
 supports unequal client/server settings without assuming either configured
-limit applies in both directions. A revision-4/error-revision-7 or older peer
-is incompatible; the ALPN is `opc-session-net/5`.
+limit applies in both directions. The exact direct profile is wire-schema
+revision 7/error-set revision 9; every non-current direct profile combination
+is incompatible. The ALPN is `opc-session-net/5`, and this profile requires a
+coordinated drained stop/upgrade/start.
+
+The 2,096,128-byte restore payload is a v5 wire-only contract value. It does
+not derive from a local backend capability or local scan budget: standalone
+SQLite may restore one 4 MiB + 64 KiB stored envelope locally. The fixed value
+reserves worst-case JSON expansion and metadata headroom below the 16 MiB
+frame. Server serialization and client response decoding both reject a page
+one byte over the fixed wire cap without emitting or accepting a partial page;
+the exact contract profile is v5/revision 7.
 
 Error-set revision 4 adds typed replication-log range overflow, page-limit,
 and compacted-cursor outcomes. A log request normalizes `start = 0` to one;
@@ -564,9 +583,11 @@ After bootstrap, the negotiated response budget applies to every response, not
 only restore pages. A non-pageable response, or a complete restore/log page
 that fits, takes the common single-encode path: it is bounded-encoded once and
 then emitted without a separate sizing serialization. If a complete pageable
-response is too large, that failed bounded encode emits no prefix; restore/log
-shaping may then use bounded logarithmic sizing probes and one final bounded
-encode. The direct attempt, every probe, final encode, prefix, payload, and
+response is too large, that failed bounded encode emits no prefix;
+replication-log shaping may then use bounded logarithmic sizing probes and one
+final bounded encode. Restore pages are validated as whole backend results and
+are never transport-shaped. The direct attempt, every probe, final encode,
+prefix, payload, and
 flush all share one absolute deadline established before the first encode or
 probe. Sizing counters and encoded storage check that deadline and
 `ServerHandle::abort` cancellation cooperatively between serializer
@@ -584,7 +605,7 @@ Response families use these fail-closed rules:
 | Fixed/scalar store or lease results | Replace an oversized backend-provided result/error with the operation's fixed SDK-owned, redaction-safe fallback when it fits; otherwise close. |
 | Get and CAS conflict records | Never truncate a record. Replace the record-bearing result with the fixed fallback, or close if even that cannot fit. |
 | Batch | Never truncate or reorder the positional result vector. Replace the complete batch response with its fixed fallback, or close. Earlier backend effects may already exist. |
-| Restore scan | Return a complete record prefix that fits and preserve `next_cursor`/excluded-count semantics. If the first record cannot fit, return the fixed restore-size error; never split a record. |
+| Restore scan | Return the complete backend page when it fits, preserving its `next_cursor`/excluded-count semantics. If the whole page exceeds the wire cap or effective frame, return the fixed restore-size error when representable or close; never trim, split, or rewrite records/cursors. |
 | Replication log | Return the largest complete contiguous entry prefix that fits. Never split an entry or skip a sequence; use the fixed fallback when no entry can fit. |
 | Watch | Bound the stream acknowledgement and every item independently. An item that cannot fit is not skipped; emit a fixed error item when representable and terminate the stream/connection so the client resumes from its last delivered sequence. |
 
@@ -770,8 +791,8 @@ Retirement has these invariants:
   explicitly.
 
 This is credential continuity, not protocol negotiation. The move to direct
-wire-schema revision 6 is still a coordinated drained stop/upgrade/start of
-every participant. After the fleet is uniformly on revision 6, leaf and trust
+wire-schema revision 7 is still a coordinated drained stop/upgrade/start of
+every participant. After the fleet is uniformly on revision 7, leaf and trust
 rotation uses the lifecycle above without a protocol downgrade or plaintext
 fallback. The bootstrap retirement control does not advance the direct or
 consensus profile revision and does not change the public API, but an older
@@ -898,8 +919,8 @@ endpoint, SPIFFE ID, certificate, key, transaction, or payload text.
   adds public `ContractProfile::max_frame_size`, so external profile struct
   literals and exhaustive destructuring must be updated in the same
   coordinated change.
-- The v5 profile pins wire-schema revision 6 and error-set revision 9;
-  `max_restore_scan_page_payload_bytes = 4194304`;
+- The v5 profile pins wire-schema revision 7 and error-set revision 9;
+  `max_restore_scan_page_payload_bytes = 2096128`;
   `max_restore_scan_examined_rows = 4096`;
   `min_frame_size = 8192`; `max_frame_size = 16777216`; the 128-byte
   owner/custom-key/state-type rules;
@@ -921,7 +942,7 @@ endpoint, SPIFFE ID, certificate, key, transaction, or payload text.
   pre-v4 peer built before #135 can still send an empty or oversized value
   that a new peer rejects before dispatch, so unchanged valid JSON shape is not
   a rolling-compatibility claim.
-- Treat every v5 exact-profile migration through wire-schema revision 6 and
+- Treat every v5 exact-profile migration through wire-schema revision 7 and
   error-set revision 9 as a
   coordinated stop/upgrade/start boundary. Drain
   traffic and writers, audit every persisted SQLite replica with the count-only
@@ -1002,8 +1023,9 @@ endpoint, SPIFFE ID, certificate, key, transaction, or payload text.
   maximum is accepted and zero means immediate expiry. The TTL request shape is
   unchanged for entries within the operation-tree contract. The new serialized
   error variants require external exhaustive matches. Their wire representation
-  was introduced by v4 error revision 1 and is retained by current error
-  revision 8; an error-revision-7 or older peer fails exact negotiation.
+  was introduced by v4 error revision 1 and is retained by current v5 error
+  revision 9. Every non-current direct profile combination fails exact
+  negotiation.
   Legacy persisted replication logs must be
   audited before upgrade because an entry carrying a larger TTL now fails
   closed during replay or rebuild rather than being clamped. Cross-field

crates/opc-session-net/src/client.rs

@@ -43,8 +43,9 @@ use crate::protocol::{
     bounded_session_op_expectations, checked_frame_size, checked_wire_frame_size,
     compare_and_set_result_matches_key, conservative_payload_budget, get_result_matches_key,
     read_frame, read_response_frame, session_op_results_match_expectations,
-    validate_request_payload_limit, validate_request_profile, write_frame_bounded_until,
-    BootstrapHello, BootstrapRequest, BootstrapResponse, ContractProfile, Request, Response,
+    validate_request_payload_limit, validate_request_profile,
+    validate_restore_scan_wire_payload_bytes, write_frame_bounded_until, BootstrapHello,
+    BootstrapRequest, BootstrapResponse, ContractProfile, Request, Response,
     RestoreScanWireRequest, CONTRACT_VERSION, CURRENT_CONTRACT_PROFILE, DEFAULT_MAX_FRAME_SIZE,
     MAX_HANDSHAKE_FRAME_SIZE, MAX_SESSION_NET_BATCH_OPERATIONS, MAX_SESSION_NET_REBUILD_ENTRIES,
     MIN_RESTORE_SCAN_RESPONSE_FRAME_SIZE, SESSION_NET_ALPN,
@@ -2324,6 +2325,16 @@ impl SessionBackend for RemoteSessionBackend {
                         "legacy_remote_restore_scan".to_string(),
                     ));
                 }
+                if let Err(error) = validate_restore_scan_wire_payload_bytes(&page.records) {
+                    self.discard_connection().await;
+                    self.clear_cached_capabilities();
+                    tracing::warn!(
+                        target = %self.target,
+                        failure = store_error_kind(&error),
+                        "remote restore scan response exceeded the wire payload limit"
+                    );
+                    return Err(error);
+                }
                 if let Err(error) = page.validate_for_request(&request) {
                     self.discard_connection().await;
                     self.clear_cached_capabilities();

crates/opc-session-net/src/lib.rs

@@ -99,7 +99,8 @@ pub use protocol::{
 };
 pub use protocol::{
     SessionConsensusContractProfile, CURRENT_SESSION_CONSENSUS_CONTRACT_PROFILE,
-    MAX_NEGOTIATED_FRAME_SIZE, MIN_SESSION_CONSENSUS_FRAME_SIZE, SESSION_CONSENSUS_ALPN,
+    MAX_NEGOTIATED_FRAME_SIZE, MIN_SESSION_CONSENSUS_FRAME_SIZE,
+    RESTORE_SCAN_MAX_WIRE_PAGE_PAYLOAD_BYTES, SESSION_CONSENSUS_ALPN,
     SESSION_CONSENSUS_TRANSPORT_REVISION,
 };
 #[cfg(feature = "legacy-session-net-compat")]