scion_stack/
lib.rs

1// Copyright 2025 Anapaya Systems
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//   http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//! SCION stack library.
15//!
16//! See `API_CONVENTIONS.md` for the naming, error, builder, and `#[non_exhaustive]` conventions
17//! this crate follows.
18
19// Linter baseline for the published API surface. See API_CONVENTIONS.md § Linting.
20#![warn(clippy::pedantic)]
21#![allow(
22    // The module path deliberately echoes type names (e.g. `stack::ScionStack`).
23    clippy::module_name_repetitions,
24    // `#[must_use]` is applied deliberately where it matters rather than everywhere.
25    clippy::must_use_candidate,
26    // `# Errors` / `# Panics` sections are added where they aid the caller, not mechanically.
27    clippy::missing_errors_doc,
28    clippy::missing_panics_doc,
29    // Casts are used deliberately in scoring/serialization hot paths.
30    clippy::cast_possible_truncation,
31    clippy::cast_precision_loss,
32    clippy::cast_sign_loss,
33    // `const`/`fn` items declared next to their use inside a function body read fine here.
34    clippy::items_after_statements,
35    // The following are stylistic preferences we deliberately do not enforce; the underlying code
36    // is intentional (object-safe `BoxFuture` trait methods, stateless scorer `&self`, explicit
37    // `match`/`if let` control flow, intentional score equality checks, fixed-size datagram
38    // buffers).
39    clippy::manual_async_fn,
40    clippy::manual_let_else,
41    clippy::single_match_else,
42    clippy::unused_self,
43    clippy::needless_pass_by_value,
44    clippy::match_same_arms,
45    clippy::ref_option,
46    clippy::large_stack_arrays,
47    clippy::float_cmp,
48    clippy::unnecessary_wraps
49)]
50
51pub mod ea_source;
52pub mod path;
53pub mod resolver;
54pub mod stack;
55pub mod underlays;
56
57pub(crate) mod internal;
58
59// Re-exported dependencies
60//
61// These crates appear in `scion-stack`'s public API by deliberate choice. They are re-exported here
62// so a client can name and construct the types our signatures require *without* adding its own
63// direct dependency — which keeps the client pinned to exactly the versions `scion-stack` was built
64// against. Reach a type through `scion_stack::<crate>::...`.
65//
66// Adding a crate to this list is a semver commitment: a breaking release of a re-exported crate is
67// a breaking change for `scion-stack`. Do not re-export a crate here unless a type from it is
68// intentionally part of the public API. Conversely, no foreign type may appear in a public
69// signature without its crate being re-exported here (see the "Dependency exposure" section of
70// `API_CONVENTIONS.md`). `tests/public_api_reexports.rs` pins these re-exports so they cannot be
71// dropped silently.
72/// Endhost API discovery models (`EndhostApiGroup`, `EndhostApiInfo`) returned by
73/// [`ea_source::EndhostApiSource`].
74pub use anapaya_ead_models;
75/// Endhost API client trait consumed by [`path::fetcher::EndhostApiSegmentFetcher::new`].
76pub use endhost_api_client;
77/// DNS resolver backend. Exposed as the escape hatch behind
78/// [`resolver::txt::ScionTxtDnsResolver::builder`] for full control over DNS resolution.
79pub use hickory_resolver;
80/// HTTP client used by the connect-RPC transport. Exposed by the `with_crpc_client` escape
81/// hatch (e.g. [`ScionStackBuilder::with_crpc_client`]) for custom name resolution / TLS.
82pub use reqwest;
83/// Authentication token-source trait (`TokenSource`) used by the `with_auth_token_source`
84/// setters.
85pub use reqwest_connect_rpc;
86/// Generic SCION UDP socket trait ([`scion_quic::socket::GenericScionUdpSocket`])
87/// that [`stack::UdpScionSocket`] implements so it can back QUIC / HTTP/3 connections.
88pub use scion_quic;
89/// SCION packet, address, path, and policy types (`ScionSocketIpAddr`, `IsdAsn`, `ScionPath`,
90/// ...).
91///
92/// This is the foundational type crate of the SDK and appears throughout `scion-stack`'s API.
93pub use sciparse;
94/// URL type used to configure endhost API / control-plane addresses.
95pub use url;
96/// X25519 key type ([`x25519_dalek::StaticSecret`]) for supplying a static SNAP identity via
97/// [`stack::builder::SnapUnderlayConfig::with_static_identity`].
98pub use x25519_dalek;
99
100// Common entry points are re-exported at the crate root for ergonomics.
101pub use crate::stack::{
102    PathUnawareUdpScionSocket, RawScionSocket, ScionStack, ScionStackBuilder, ScmpScionSocket,
103    SocketConfig, UdpScionSocket,
104};
scion_stack/lib.rs

scion_stack/
lib.rs
