alksocks 0.1.0

SOCKS5 (RFC 1928) proxy protocol over alkcall channels: targeted-forked fast-socks5 typestate core plus producer/consumer sessions. Producer/consumer protocol crate.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! alksocks — SOCKS5 (RFC 1928) as a produced resource on alkcall
//! channels.
//!
//! A producer/consumer protocol crate (the alktty/alktunnels shape):
//! the producer half registers the `channels/socks5/sub` open op and
//! drives the RFC 1928 conversation in-stream over the channel's
//! `BiStream`; the consumer half opens SOCKS5 channels and speaks the
//! protocol inside them. The defining posture: the protocol never
//! binds a port — kernel binds exist only as explicit, feature-gated
//! assembly shapes (`local`), never in the protocol layer.
//!
//! ## The landed surface (the protocol core)
//!
//! - **The wire vocabulary and the explicit typestate** live in
//!   [`rfc1928`]: a targeted fork of fast-socks5 v1.0.0's `T`-generic
//!   subset (MIT, third-party upstream) carrying two deliberate
//!   changes (BIND support, `new_reply` publication) — see
//!   `docs/architecture/rfc1928.md`, ADR-013, and ADR-011.
//! - **The wire codec** ([`wire`]): the ASSOCIATE datagram frame
//!   (`[len: u16 BE][addr + data]`, ADR-003) — framing is applied
//!   exactly once, by this layer; the egress speaks inner bytes.
//! - **The wire-stable open-op surface** ([`params`]): the
//!   `channels/socks5/sub` op id, the `alk/socks5` ALPN, the
//!   trivial `{}` params (ADR-001), and the two scope constants
//!   (`socks5:open`, `socks5:bind` — two grants, never implied,
//!   ADR-006). The typed open-error vocabulary lives in [`error`].
//! - **The three seams** ([`egress`]): `DialFn` / `EgressFactory` /
//!   `BindAcceptFactory` (ADR-004) — functions, not traits, at the
//!   three I/O planes; ownership rides the handle structurally; the
//!   egress readiness contract (`next_reply` `Pending` when nothing
//!   is ready) is load-bearing API.
//! - **The producer half** ([`producer`]): the session-gate
//!   establisher, the command-dispatch pump (CONNECT pass-through /
//!   ASSOCIATE datagram stage / BIND phase model), the scope gates
//!   (the open gate `socks5:open` at the registry; the command gate
//!   `socks5:bind` at BIND dispatch), and
//!   [`register_socks5_openable`] — substrate-agnostic over the
//!   seams; never a bind in the protocol layer.
//! - **The consumer half** ([`consumer`]): the typed channels-native
//!   sessions — [`Socks5ChannelSession`] (CONNECT),
//!   [`AssociateSession`] (the framed datagram stage),
//!   [`BindSession`] (the reply#1/reply#2 reader) — each owning its
//!   channel's teardown; no `Clone`. The cred-bearing front door's
//!   re-origination rides the token-carrying surface (`TokenClient`
//!   + the `*_with_token` constructor twins).
//!
//! The assembly layer (feature-gated, ADR-008/009): `local` (the
//! socket-backed providers — `local::tcp_dial` / `local::udp_egress`
//! / `local::bind_accept` — plus the producer-side
//! `local::ProducerDoor`) and `door` (the consumer's front doors —
//! the NoAuth raw-pipe + RFC 1929 cred-bearing `FrontDoor`, the
//! `UdpFrontDoor` with the RFC codec at the door boundary only,
//! ADR-005/003/014) ride `local`; the composed providers
//! (`composed::direct_egress` — the alktunnels direct-op egress,
//! `composed::bindfirst_accept` — the bind-first accept,
//! ADR-007/008) ride `composed`. The default crate is protocol-only
//! and wasm-clean by construction.
//!
//! Architecture: `docs/architecture/overview.md` (spec set:
//! wire.md, producer.md, consumer.md, rfc1928.md); the cross-cutting
//! behavior is pinned end to end by `tests/core-integration.rs` (the
//! protocol core: one registration, all three commands; concurrency;
//! the teardown matrix; the identity/scope matrix; the readiness
//! contract) and `tests/assembly-integration.rs` (the assembly
//! layer: the full `-D` story through the doors, the composed
//! variant set, mixed assembly, the assembly teardown matrix).

#![forbid(unsafe_code)]

pub mod rfc1928;

pub mod consumer;
pub mod egress;
pub mod error;
pub mod params;
pub mod producer;
pub mod wire;

#[cfg(feature = "local")]
pub mod local;

#[cfg(feature = "composed")]
pub mod composed;

#[cfg(feature = "local")]
pub mod door;

/// The shared test helpers (review 002 N-5): the single-sourced
/// harness shapes, compiled into the lib test crate. The file lives
/// under `tests/common/` so the integration suite reaches the same
/// copy through its own `mod` declaration (`tests/harness.rs`
/// re-exports the consumed subset). `#[cfg(test)]` keeps it out of
/// the published crate; the `#[path]` resolves relative to `src/`.
#[cfg(test)]
#[path = "../tests/common/mod.rs"]
pub(crate) mod test_common;

// The shared module is written once against the extern-crate paths
// (`alksocks::`) the integration suite resolves; inside the lib test
// crate those same paths resolve via this alias (`extern crate`
// self-linkage, the standard `mod common` companion).
#[cfg(test)]
extern crate self as alksocks;

pub use consumer::{
    AssociateSession, BindDataPlane, BindReply1, BindSession, Socks5ChannelSession,
    SpentSessionError, TakenAssociateInner,
};
pub use egress::{
    egress_factory, BindAccept, BindAcceptError, BindAcceptFactory, BindAcceptFactoryError,
    BindTargetHandle, DialFn, Egress, EgressError, EgressFactory, SocksDialError, TargetHandle,
};
pub use error::{
    ReplyError, SocksError, SocksEstablishmentReason, SocksOpenError, SocksServerError,
    SocksSessionError,
};
pub use params::{
    establishment_reason, socks5_open_spec, Socks5Params, OP_SOCKS5_OPEN, SOCKS5_ALPN,
    SOCKS5_BIND_SCOPE, SOCKS5_OPEN_SCOPE,
};
pub use producer::{
    make_socks5_pump_handler, register_socks5_openable, serve_socks5_over,
    socks5_session_establisher, IdentityWitness, Socks5Producer, Socks5ProducerBuilder,
};
pub use wire::{addr_encoding_len, frame, frame_inner, DatagramReader, WireError, MAX_INNER_LEN};

#[cfg(feature = "local")]
pub use local::{bind_accept, tcp_dial, udp_egress, LocalEgress};

#[cfg(feature = "local")]
pub use local::{ProducerDoor, ProducerDoorBuilder, ProducerDoorGuard};

#[cfg(feature = "composed")]
pub use composed::{
    bindfirst_accept, direct_egress, key_of, register_forwarded_serving, substrate_addr_of,
    ComposedEgress, CorrelationRegistry, ForwardedSession, SessionOwner, DEFAULT_MAX_TUNNELS,
};

#[cfg(feature = "local")]
pub use consumer::{TokenClient, TokenClientError};
#[cfg(feature = "local")]
pub use door::{CredentialTable, DoorBuildError, DoorCredential, FrontDoor, UdpFrontDoor};
#[cfg(feature = "local")]
pub use local::{ProducerDoorBuildError, ProducerDoorError};