docs: remove em dashes from repo prose and forbid them going forward
- Rewrote em dash prose across the whole tree outside docs/reviews/ (the historical reviews stay verbatim, matching the alktunnels and alktty precedent): src doc comments and inline comments (587), docs/architecture (319), docs/research + sdd_process (484), tests (361), tasks (899), fuzz (28), README/CHANGELOG/Cargo.toml (77), AGENTS.md (85), and the .opencode/agents prompts (109) - Fenced content follows the precedent: comments, ASCII-diagram label separators, and template placeholders rewritten; wire data, JSON/BAST documents, byte diagrams, and transcripts survive verbatim; assert, expect, panic, error-display, and format message literals rewritten as prose; no code, fixture, or test data change - src/rfc1928/LICENSE: the two dashes in alksocks' own provenance header rewritten; the MIT legal text untouched - AGENTS.md adds Project Convention 18: no em dashes in prose; varied restructure, no spaced-hyphen substitutes, fenced prose rule, en dash numeric ranges exempt, docs/reviews/ exempt from the greps - tasks/*.md frontmatter: the name values rewritten by the sweep are now quoted (a raw colon inside an unquoted YAML scalar parsed as null); taskgraph validate reports 37 tasks, no issues Verification: cargo test; cargo clippy --all-targets -D warnings; cargo fmt --check; cargo doc --no-deps; fuzz corpus replay (cargo test --manifest-path fuzz/shared/Cargo.toml); wasm check and clippy for wasm32-unknown-unknown with -D warnings; em dash grep over the repo returns matches only in docs/reviews/ and the bast.md BAST JSON data fence
This commit is contained in:
1 parent
9ca8c52601
commit
e196ed43e3
115 files changed
+3593
-3531
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: implementation/core-consumer-associate
|
||||
name: "Core — consumer ASSOCIATE: AssociateSession + e2e tests"
|
||||
name: "Core: consumer ASSOCIATE, AssociateSession + e2e tests"
|
||||
status: completed
|
||||
depends_on: [implementation/core-consumer-connect, implementation/core-producer-associate]
|
||||
scope: moderate
|
||||
@@ -20,20 +20,20 @@ Deliverables (port from `/workspace/alksocks-udp-poc/src/consumer.rs`,
|
||||
adapted to the crate's wire codec):
|
||||
|
||||
1. **`AssociateSession::associate(client)`**: opens the channel,
|
||||
negotiates (NoAuth), sends ASSOCIATE, reads the reply —
|
||||
negotiates (NoAuth), sends ASSOCIATE, reads the reply;
|
||||
**receives the sentinel BND.ADDR and never uses it for
|
||||
addressing** (the handle is the channel; ADR-003).
|
||||
2. **`send_datagram(dst, bytes)`**: frames once
|
||||
(`[len: u16 BE][addr + data]` via the crate's wire codec — the
|
||||
(`[len: u16 BE][addr + data]` via the crate's wire codec, the
|
||||
framing-once mirror) and writes the frame.
|
||||
3. **`recv_datagram()`** returns `(source_addr, bytes)` per
|
||||
datagram — **the incremental reader state (mid-frame position +
|
||||
datagram, and **the incremental reader state (mid-frame position +
|
||||
batched-datagram pending queue) persists across calls**: a
|
||||
datagram split across channel chunks survives a caller-driven
|
||||
receive loop (POC #2's finding — the first cut dropped the reader
|
||||
receive loop (POC #2's finding: the first cut dropped the reader
|
||||
state per call; the 2-byte-prefix chunk test exposed it). Write
|
||||
the persistence test (the POC's chunk-splitting echo shape).
|
||||
4. **`shutdown()`** half-closes the stream — the mux's implicit-EOF
|
||||
4. **`shutdown()`** half-closes the stream: the mux's implicit-EOF
|
||||
sentinel reaches the producer's stage as EOF and the association
|
||||
ends (association lifetime = channel lifetime).
|
||||
5. **Teardown ownership**: the session owns the channel; on Drop it
|
||||
@@ -68,12 +68,12 @@ adapted to the crate's wire codec):
|
||||
- docs/architecture/decisions/003-udp-handle-swap.md (the consumer
|
||||
mirror invariants)
|
||||
- POC source: `/workspace/alksocks-udp-poc/src/consumer.rs`
|
||||
(`UdpAssociation` — the reader-state finding's origin)
|
||||
(`UdpAssociation`, the reader-state finding's origin)
|
||||
|
||||
## Notes
|
||||
|
||||
- **`send_datagram` takes `impl ToTargetAddr`** (the CONNECT
|
||||
session's target-construction posture — ADR-012: IP-string forms
|
||||
session's target-construction posture; under ADR-012, IP-string forms
|
||||
parse, domains pass through unresolved), not the POC's
|
||||
`&TargetAddr`: the same entry shape as `connect`. A
|
||||
`ToTargetAddr for &TargetAddr` impl was added to the forked
|
||||
@@ -81,7 +81,7 @@ adapted to the crate's wire codec):
|
||||
`TargetAddr` value across sends.
|
||||
- **Teardown ownership matches the CONNECT/BIND sessions** (the
|
||||
crate's posture, strengthened from the POC's "close/join"): the
|
||||
session owns the adopted channel entry — Drop sync-reaps
|
||||
session owns the adopted channel entry; Drop sync-reaps
|
||||
(`teardown_channel`, best-effort; `Drop` cannot await) + the data
|
||||
plane EOFs structurally (the mux's implicit-EOF sentinel);
|
||||
`shutdown()` half-closes (the graceful path, returning the reap
|
||||
@@ -92,27 +92,28 @@ adapted to the crate's wire codec):
|
||||
- **`recv_datagram` returns `Result<Option<(TargetAddr, Bytes)>>`**
|
||||
(the POC's shape): `Ok(None)` = channel EOF (the association's
|
||||
end); a stream end mid-frame is fail-loud (an `UnexpectedEof`
|
||||
I/O error through `SocksSessionError::Rfc` — never a silent
|
||||
I/O error through `SocksSessionError::Rfc`; never a silent
|
||||
partial datagram); an undecodable frame (garbage ATYP) errors
|
||||
loud through the wire codec's `WireError` → RFC mapping
|
||||
(`AddrError` class for address-encoding refusals,
|
||||
`UdpHeaderError` for the garbage shapes — the consumer-side
|
||||
`UdpHeaderError` for the garbage shapes, the consumer-side
|
||||
mirror of the producer stage's `UndecodableFrame` exit).
|
||||
- **The pending queue stores decoded datagrams** (`(TargetAddr,
|
||||
Bytes)`) — the POC stored pre-decode inner bytes; decoded storage
|
||||
keeps the delivery shape uniform (decode once per frame either
|
||||
way; no wire.rs change needed — `decode_inner` stays private).
|
||||
Bytes)`) rather than the POC's pre-decode inner bytes; decoded
|
||||
storage keeps the delivery shape uniform (decode once per frame
|
||||
either way; no wire.rs change needed, since `decode_inner` stays
|
||||
private).
|
||||
- **Unit tests ride a duplex-backed session** (`skip_auth`'s
|
||||
handshake-free `use_stream` path over a `BiStream::from_joined`
|
||||
duplex — no channels needed) for the reader-internals probes:
|
||||
duplex, no channels needed) for the reader-internals probes:
|
||||
reader-state persistence (the 2-byte-prefix chunk shape, the POC
|
||||
finding's trigger), mid-frame EOF fail-loud, garbage-ATYP fail-
|
||||
loud, and the wire-error mapping table.
|
||||
- **The e2e split-datagram test uses a 60 KiB payload** (60007
|
||||
inner bytes — legal under the u16 joint bound, well over the 16
|
||||
inner bytes, legal under the u16 joint bound, well over the 16
|
||||
KB read buffer): first → big → third, in order, with the big
|
||||
datagram reassembling across the call boundary and the third
|
||||
drained through the pending queue — both halves of the
|
||||
drained through the pending queue; both halves of the
|
||||
persistence invariant pinned end to end.
|
||||
- **No harness changes**: the consumer-side topology's
|
||||
`wire_consumer_side_with` + the producer-associate task's
|
||||
@@ -127,20 +128,20 @@ adapted to the crate's wire codec):
|
||||
Implemented the UDP ASSOCIATE consumer session in `src/consumer.rs`
|
||||
(POC #2's shape, adapted to the crate's teardown-owning session
|
||||
posture): `AssociateSession::associate` (open → no-auth → ASSOCIATE
|
||||
→ reply, capturing the sentinel BND.ADDR as `relay_addr()` —
|
||||
received, never used for addressing; the ASSOCIATE DST.ADDR is the
|
||||
→ reply, capturing the sentinel BND.ADDR as `relay_addr()`,
|
||||
received but never used for addressing; the ASSOCIATE DST.ADDR is the
|
||||
vanilla-mirror unspecified address), `send_datagram` (frames once
|
||||
via the crate's wire `frame()` — the framing-once mirror, the joint
|
||||
via the crate's wire `frame()` (the framing-once mirror, the joint
|
||||
bound enforced at frame time), `recv_datagram` (the incremental
|
||||
`DatagramReader` + batched-datagram pending queue, **state that
|
||||
persists across calls** — the POC's reader-state finding, with the
|
||||
persists across calls**; that is the POC's reader-state finding, with the
|
||||
fail-loud shapes: mid-frame EOF and undecodable frames), `shutdown`
|
||||
(the half-close; the mux's implicit-EOF sentinel reaches the
|
||||
producer's stage as EOF — association lifetime = channel lifetime),
|
||||
producer's stage as EOF; association lifetime = channel lifetime),
|
||||
plus `split`/`into_inner` accessors and the CONNECT sessions'
|
||||
teardown ownership (Drop sync-reap + structural EOF, `close()`
|
||||
graceful, teardown-at-birth on in-stream refusals, no `Clone` —
|
||||
`compile_fail`-asserted). Typed error surface throughout: open
|
||||
graceful, teardown-at-birth on in-stream refusals, no `Clone`,
|
||||
since `compile_fail` is asserted there). Typed error surface throughout: open
|
||||
failures are `SocksSessionError::Open` (ADR-049 reasons); the
|
||||
missing-egress 0x07 and factory-failure codes surface from
|
||||
`associate` as `Rfc`. E2E suite (`tests/consumer-associate.rs`, 8
|
||||
@@ -153,6 +154,6 @@ Drop teardown + connection health, the missing-egress refusal
|
||||
(typed 0x07, no phantom channel), the egress-factory failure
|
||||
mapping, and the CONNECT+ASSOCIATE regression guard on one
|
||||
registration (interleaved, both serving). Verification: `cargo
|
||||
test` 305 (incl. the 3 doctests — the compile-fail assertions ride
|
||||
test` 305 (incl. the 3 doctests; the compile-fail assertions ride
|
||||
among them), clippy `-D warnings` (all targets), fmt, `cargo doc
|
||||
--no-deps`, and both wasm checks clean.
|
||||
Reference in new issue
Block a user