From 07e5901cabd5befa46210072faf0ab2c44f76d94 Mon Sep 17 00:00:00 2001 From: konard Date: Wed, 7 Oct 2026 02:21:47 +0000 Subject: [PATCH 1/3] Initial commit with task details Adding .gitkeep for PR creation (default mode). This file will be removed when the task is complete. Issue: https://github.com/link-foundation/links-queue/issues/51 --- .gitkeep | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitkeep diff --git a/.gitkeep b/.gitkeep new file mode 100644 index 0000000..efa7e84 --- /dev/null +++ b/.gitkeep @@ -0,0 +1 @@ +# .gitkeep file auto-generated at 2026-10-07T02:21:47.652Z for PR creation at branch issue-51-da669128bb7c for issue https://github.com/link-foundation/links-queue/issues/51 \ No newline at end of file From 8590aacf1f345f0c18ec0f6b20523b8824e2e7ec Mon Sep 17 00:00:00 2001 From: konard Date: Wed, 7 Oct 2026 02:29:17 +0000 Subject: [PATCH 2/3] Correct self-referencing binary notation specification --- .gitkeep | 1 - docs/BINARY-NOTATION-SPEC.md | 28 ++++--- js/.changeset/self-referencing-binary-spec.md | 5 ++ js/tests/binary-notation-spec.test.js | 79 +++++++++++++++++++ ...007_022500_self_referencing_binary_spec.md | 7 ++ rust/src/backends/binary_notation_tests.rs | 64 ++++++++++++++- 6 files changed, 172 insertions(+), 12 deletions(-) delete mode 100644 .gitkeep create mode 100644 js/.changeset/self-referencing-binary-spec.md create mode 100644 js/tests/binary-notation-spec.test.js create mode 100644 rust/changelog.d/20261007_022500_self_referencing_binary_spec.md diff --git a/.gitkeep b/.gitkeep deleted file mode 100644 index efa7e84..0000000 --- a/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -# .gitkeep file auto-generated at 2026-10-07T02:21:47.652Z for PR creation at branch issue-51-da669128bb7c for issue https://github.com/link-foundation/links-queue/issues/51 \ No newline at end of file diff --git a/docs/BINARY-NOTATION-SPEC.md b/docs/BINARY-NOTATION-SPEC.md index 6e8bf89..05f600f 100644 --- a/docs/BINARY-NOTATION-SPEC.md +++ b/docs/BINARY-NOTATION-SPEC.md @@ -1,6 +1,6 @@ # Binary Links Notation Specification -**Version**: 1.0.0 +**Version**: 1.0.1 (documentation revision; wire version remains 1.0) **Status**: Draft **Authors**: links-queue contributors @@ -53,10 +53,10 @@ Every binary message starts with a fixed 11-byte header: Each link is encoded with a type byte followed by variable-length fields: ``` -┌────────┬────────────┬────────────┬──────────────┐ -│ Type │ Source │ Target │ Values (opt) │ -│ 1 byte │ Variable │ Variable │ Variable │ -└────────┴────────────┴────────────┴──────────────┘ +┌────────┬────────────┬────────────┬────────────┬──────────────┐ +│ Type │ ID (opt) │ Source │Target (opt)│ Values (opt) │ +│ 1 byte │ VarInt │ Variable │ Variable │ Variable │ +└────────┴────────────┴────────────┴────────────┴──────────────┘ ``` #### Type Byte @@ -65,12 +65,16 @@ Each link is encoded with a type byte followed by variable-length fields: |-----|------|-------------| | 0 | SOURCE_IS_ID | Source is a link ID reference (vs inline link/literal) | | 1 | TARGET_IS_ID | Target is a link ID reference (vs inline link/literal) | -| 2 | SELF_REF | Self-referencing link (source == target, only encode once) | +| 2 | SELF_REF | Source and target are equal numeric ID references; encode the source and omit the target | | 3 | HAS_ID | Link has an explicit ID | | 4 | HAS_VALUES | Link has additional values array | | 5-6 | ID_SIZE | 00=varint, 01=4 bytes, 10=8 bytes, 11=reserved | | 7 | RESERVED | Reserved for future use | +Fields appear in this order: type, explicit ID if `HAS_ID` is set, source, target unless `SELF_REF` is set, and values if `HAS_VALUES` is set. The source is always encoded, including when it equals the explicit ID. + +`SELF_REF` only indicates that source equals target; the link's explicit ID may differ from both. For example, `(7: 5 5)` has body bytes `0F 07 05`. `HAS_ID` and `SELF_REF` are independent: combining them does not omit the source or imply that it equals the explicit ID. + ### Value Encoding Values can be: @@ -123,6 +127,8 @@ Arrays are encoded as: ## Examples +The sizes below describe link bodies only. They exclude the 11-byte message header and the payload's VarInt link count. + ### Simple Link `(1, 2)` Text notation: `(1 2)` (5 bytes) @@ -134,16 +140,19 @@ Target: 0x02 (varint 2) Total: 3 bytes (40% reduction) ``` -### Self-Referencing Link `(5: 5)` +### Self-Referencing Link `(5: 5 5)` -Text notation: `(5: 5 5)` (10 bytes) +Text notation: `(5: 5 5)` (8 bytes) Binary encoding: ``` Type: 0x0F (SOURCE_IS_ID | TARGET_IS_ID | SELF_REF | HAS_ID) ID: 0x05 (varint 5) -Total: 2 bytes (80% reduction) +Source: 0x05 (varint 5; target reuses source) +Total: 3 bytes (62.5% reduction) ``` +The body bytes are `0F 05 05`. The explicit ID and the shared source/target reference are separate fields, even though both equal 5. This corrects the example without changing the version 1.0 wire format (`0x0100`). + ### Named Link `(type: enqueue)` Text notation: `(type: enqueue)` (15 bytes) @@ -336,6 +345,7 @@ socket.on('data', (chunk) => { | Version | Date | Changes | |---------|------|---------| +| 1.0.1 | 2026-10 | Clarify independent ID and source fields; correct self-referencing example sizes (wire version unchanged) | | 1.0.0 | 2024-01 | Initial specification | ## References diff --git a/js/.changeset/self-referencing-binary-spec.md b/js/.changeset/self-referencing-binary-spec.md new file mode 100644 index 0000000..1ccb306 --- /dev/null +++ b/js/.changeset/self-referencing-binary-spec.md @@ -0,0 +1,5 @@ +--- +'links-queue-js': patch +--- + +Correct the binary notation specification's self-referencing example to `0F 05 05` (3 bytes versus 8 text bytes, a 62.5% reduction). Clarify that the explicit ID and shared source/target reference are independent fields, and add specification and wire compatibility tests without changing the version 1.0 encoding. diff --git a/js/tests/binary-notation-spec.test.js b/js/tests/binary-notation-spec.test.js new file mode 100644 index 0000000..a0f9095 --- /dev/null +++ b/js/tests/binary-notation-spec.test.js @@ -0,0 +1,79 @@ +/** Tests that the self-referencing specification example matches the wire format. */ + +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { + BinaryNotation, + HEADER_SIZE, + encodeLinkBody, + decodeLinkBody, + linkBodySize, +} from '../src/protocol/binary-notation.js'; + +const specification = readFileSync( + new URL('../../docs/BINARY-NOTATION-SPEC.md', import.meta.url), + 'utf8' +); +const example = specification + .split('### Self-Referencing Link')[1] + .split('\n### ')[0]; +const documentedBody = Uint8Array.from( + example.matchAll(/^(?:Type|ID|Source|Target): 0x([0-9a-f]+)/gim), + ([, hex]) => Number.parseInt(hex, 16) +); +const [, text, textBytes] = example.match( + /Text notation: `([^`]+)` \((\d+) bytes\)/ +); +const [, bodyBytes, reduction] = example.match( + /Total: (\d+) bytes \(([\d.]+)% reduction\)/ +); + +describe('Self-referencing specification example', () => { + it('should match the encoded body and decode to the example link', () => { + const link = { id: 5, source: 5, target: 5 }; + const frame = BinaryNotation.encode(link); + assert.deepEqual(frame.slice(HEADER_SIZE + 1), documentedBody); + const decoded = decodeLinkBody(documentedBody, 0); + assert.equal(decoded.bytesRead, documentedBody.length); + assert.equal(decoded.link.id, link.id); + assert.equal(decoded.link.source, link.source); + assert.equal(decoded.link.target, link.target); + }); + + it('should report the UTF-8 text size accurately', () => { + assert.equal(new TextEncoder().encode(text).length, Number(textBytes)); + }); + + it('should report the body size and reduction without framing overhead', () => { + const size = linkBodySize({ id: 5, source: 5, target: 5 }); + assert.equal(size, Number(bodyBytes)); + assert.equal(size, documentedBody.length); + assert.equal(((1 - size / Number(textBytes)) * 100).toFixed(1), reduction); + }); +}); + +describe('Version 1.0 self-referencing wire format', () => { + const cases = [ + { id: 5, reference: 5, bytes: [0x0f, 0x05, 0x05] }, + { id: 7, reference: 5, bytes: [0x0f, 0x07, 0x05] }, + { id: 128, reference: 128, bytes: [0x0f, 0x80, 0x01, 0x80, 0x01] }, + { id: null, reference: 5, bytes: [0x07, 0x05] }, + ]; + + for (const { id, reference, bytes } of cases) { + it(`should encode ID ${id} and shared reference ${reference}`, () => { + const link = { id, source: reference, target: reference }; + const body = Uint8Array.from(bytes); + const buffer = new Uint8Array(body.length); + assert.equal(encodeLinkBody(link, buffer, 0), body.length); + assert.equal(linkBodySize(link), body.length); + assert.deepEqual(buffer, body); + const decoded = decodeLinkBody(body, 0); + assert.equal(decoded.bytesRead, body.length); + assert.equal(decoded.link.id, id ?? 0); + assert.equal(decoded.link.source, reference); + assert.equal(decoded.link.target, reference); + }); + } +}); diff --git a/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md b/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md new file mode 100644 index 0000000..19ae09f --- /dev/null +++ b/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Fixed + +- Correct the binary notation specification's self-referencing example to `0F 05 05` (3 bytes versus 8 text bytes, a 62.5% reduction). Clarify independent ID and source fields and verify the documented bytes against the Rust codec while preserving the version 1.0 wire format. diff --git a/rust/src/backends/binary_notation_tests.rs b/rust/src/backends/binary_notation_tests.rs index 071d307..0c89593 100644 --- a/rust/src/backends/binary_notation_tests.rs +++ b/rust/src/backends/binary_notation_tests.rs @@ -101,8 +101,9 @@ mod link_tests { let mut buf = Vec::new(); let size = encode_link_body(&link, &mut buf).unwrap(); - // Self-ref should be compact - assert!(size <= 3); + assert_eq!(size, 3); + assert_eq!(buf, vec![0x0F, 0x05, 0x05]); + assert_eq!(link_body_size(&link), size); let mut cursor = std::io::Cursor::new(buf); let decoded = decode_link_body(&mut cursor).unwrap(); @@ -112,6 +113,65 @@ mod link_tests { assert!(matches!(decoded.target, EncodedValue::Int(5))); } + #[test] + fn test_self_ref_specification_example() { + let specification = include_str!("../../../docs/BINARY-NOTATION-SPEC.md"); + let example = specification + .split("### Self-Referencing Link") + .nth(1) + .unwrap() + .split("\n### ") + .next() + .unwrap(); + let documented_body: Vec = example + .lines() + .filter_map(|line| { + let (field, value) = line.split_once(": 0x")?; + if matches!(field, "Type" | "ID" | "Source" | "Target") { + Some(u8::from_str_radix(value.split_whitespace().next().unwrap(), 16).unwrap()) + } else { + None + } + }) + .collect(); + let link = EncodedLink::new(Some(5), EncodedValue::Int(5), EncodedValue::Int(5)); + let frame = BinaryNotation::encode(&[link], None).unwrap(); + assert_eq!(&frame[HEADER_SIZE + 1..], documented_body); + + let mut cursor = std::io::Cursor::new(documented_body); + let decoded = decode_link_body(&mut cursor).unwrap(); + assert_eq!(decoded.id, Some(5)); + assert!(matches!(decoded.source, EncodedValue::Int(5))); + assert!(matches!(decoded.target, EncodedValue::Int(5))); + assert_eq!(cursor.position(), 3); + } + + #[test] + fn test_self_ref_wire_format() { + let cases: [(Option, u64, &[u8]); 3] = [ + (Some(7), 5, &[0x0F, 0x07, 0x05]), + (Some(128), 128, &[0x0F, 0x80, 0x01, 0x80, 0x01]), + (None, 5, &[0x07, 0x05]), + ]; + for (id, reference, body) in cases { + let link = EncodedLink::new( + id, + EncodedValue::Int(reference), + EncodedValue::Int(reference), + ); + let mut buffer = Vec::new(); + assert_eq!(encode_link_body(&link, &mut buffer).unwrap(), body.len()); + assert_eq!(link_body_size(&link), body.len()); + assert_eq!(buffer, body); + let mut cursor = std::io::Cursor::new(body); + let decoded = decode_link_body(&mut cursor).unwrap(); + assert_eq!(decoded.id, id); + assert!(matches!(decoded.source, EncodedValue::Int(n) if n == reference)); + assert!(matches!(decoded.target, EncodedValue::Int(n) if n == reference)); + assert_eq!(cursor.position(), body.len() as u64); + } + } + #[test] fn test_encode_decode_link_with_values() { let link = EncodedLink::with_values( From 12366b45c3b4105592e16df85791176eb6b2e02e Mon Sep 17 00:00:00 2001 From: konard Date: Wed, 7 Oct 2026 02:38:18 +0000 Subject: [PATCH 3/3] Restore strict Rust CI checks on current Clippy --- rust/Cargo.toml | 4 ++++ .../20261007_022500_self_referencing_binary_spec.md | 1 + rust/src/backends/binary_notation.rs | 2 +- rust/src/backends/link_cli.rs | 3 +-- rust/src/backends/memory_backend.rs | 3 +-- rust/src/client/connection.rs | 3 +-- rust/src/cluster/node.rs | 7 ++----- rust/src/queue/manager.rs | 4 ++-- rust/tests/link_cli_integration.rs | 3 +-- 9 files changed, 14 insertions(+), 16 deletions(-) diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 0bcceab..5b939df 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -82,6 +82,10 @@ module_name_repetitions = "allow" too_many_lines = "allow" missing_errors_doc = "allow" missing_panics_doc = "allow" +# Async implementations retain deferred execution even when no await is needed. +unused_async_trait_impl = "allow" +# is_empty assertions also work for collections of types without PartialEq. +assert_is_empty = "allow" [profile.release] lto = true diff --git a/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md b/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md index 19ae09f..ba7ef1b 100644 --- a/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md +++ b/rust/changelog.d/20261007_022500_self_referencing_binary_spec.md @@ -5,3 +5,4 @@ bump: patch ### Fixed - Correct the binary notation specification's self-referencing example to `0F 05 05` (3 bytes versus 8 text bytes, a 62.5% reduction). Clarify independent ID and source fields and verify the documented bytes against the Rust codec while preserving the version 1.0 wire format. +- Restore strict Clippy checks on current Rust toolchains with equivalent helper expressions and explicit allowances for deferred async implementations and collection emptiness assertions. diff --git a/rust/src/backends/binary_notation.rs b/rust/src/backends/binary_notation.rs index 9072513..9908258 100644 --- a/rust/src/backends/binary_notation.rs +++ b/rust/src/backends/binary_notation.rs @@ -901,7 +901,7 @@ impl BinaryNotation { /// Checks if data appears to be binary notation. #[must_use] - pub fn is_binary(data: &[u8]) -> bool { + pub const fn is_binary(data: &[u8]) -> bool { if data.len() < 4 { return false; } diff --git a/rust/src/backends/link_cli.rs b/rust/src/backends/link_cli.rs index 39be4d7..d4a12c0 100644 --- a/rust/src/backends/link_cli.rs +++ b/rust/src/backends/link_cli.rs @@ -266,8 +266,7 @@ impl LinkCliBackend { fn current_time_ms() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) - .map(|d| d.as_millis() as u64) - .unwrap_or(0) + .map_or(0, |d| d.as_millis() as u64) } /// Ensures the backend is connected. diff --git a/rust/src/backends/memory_backend.rs b/rust/src/backends/memory_backend.rs index 6a518e3..cb4fd73 100644 --- a/rust/src/backends/memory_backend.rs +++ b/rust/src/backends/memory_backend.rs @@ -177,8 +177,7 @@ impl MemoryBackend { fn current_time_ms() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) - .map(|d| d.as_millis() as u64) - .unwrap_or(0) + .map_or(0, |d| d.as_millis() as u64) } /// Ensures the backend is connected, returning an error if not. diff --git a/rust/src/client/connection.rs b/rust/src/client/connection.rs index 08f5b98..1c19581 100644 --- a/rust/src/client/connection.rs +++ b/rust/src/client/connection.rs @@ -236,8 +236,7 @@ where // Use try_read to avoid blocking self.state .try_read() - .map(|s| *s == ConnectionState::Connected) - .unwrap_or(false) + .is_ok_and(|s| *s == ConnectionState::Connected) } fn server_address(&self) -> Option { diff --git a/rust/src/cluster/node.rs b/rust/src/cluster/node.rs index 4bc29d2..5d7cffc 100644 --- a/rust/src/cluster/node.rs +++ b/rust/src/cluster/node.rs @@ -295,10 +295,7 @@ impl ClusterNode for Node { fn status(&self) -> NodeStatus { // Use try_read to avoid blocking, default to Joining if locked - self.status - .try_read() - .map(|s| *s) - .unwrap_or(NodeStatus::Joining) + self.status.try_read().map_or(NodeStatus::Joining, |s| *s) } async fn ping(&self) -> Result { @@ -578,7 +575,7 @@ mod tests { assert_eq!(node.last_latency(), Duration::ZERO); node.update_latency(Duration::from_millis(50)); - assert_eq!(node.last_latency(), Duration::from_micros(50000)); + assert_eq!(node.last_latency(), Duration::from_millis(50)); } } diff --git a/rust/src/queue/manager.rs b/rust/src/queue/manager.rs index a13c624..d637e8e 100644 --- a/rust/src/queue/manager.rs +++ b/rust/src/queue/manager.rs @@ -170,8 +170,8 @@ impl MemoryQueueManager { let dead_letters: Vec<(String, Vec>)> = { let queues = self.queues.lock().expect("lock poisoned"); queues - .iter() - .filter_map(|(_, entry)| { + .values() + .filter_map(|entry| { let dlq_name = entry.queue.dead_letter_queue_name()?; let items = entry.queue.drain_dead_letters(); if items.is_empty() { diff --git a/rust/tests/link_cli_integration.rs b/rust/tests/link_cli_integration.rs index 7eee145..91a93e0 100644 --- a/rust/tests/link_cli_integration.rs +++ b/rust/tests/link_cli_integration.rs @@ -20,8 +20,7 @@ fn clink_available() -> bool { std::process::Command::new("clink") .arg("--version") .output() - .map(|output| output.status.success()) - .unwrap_or(false) + .is_ok_and(|output| output.status.success()) } /// Checks if tests should be skipped.