Standard library¶

Gossamer's standard library ships as a Rust-implemented host crate (gossamer-std) with a manifest describing every module and item. This page is auto-generated from that manifest via cargo xtask docs-stdlib; hand edits are overwritten on the next regeneration.

The manifest itself lives at crates/gossamer-std/src/manifest.rs.

Modules¶

Module	Items	Summary
std::bufio	3	Buffered readers, writers, and line scanners.
std::bytes	5	Byte buffers, builders, and slice helpers.
std::collections	6	Built-in container types.
std::compress::gzip	3	gzip encoder / decoder (RFC 1952; flate2-backed).
std::context	5	Request-scoped cancellation, deadlines, and timeouts.
std::crypto::hmac	1	HMAC-SHA-256 keyed MACs.
std::crypto::rand	2	Secure random bytes from the host CSPRNG.
std::crypto::sha256	2	SHA-256 hashing.
std::crypto::subtle	1	Constant-time comparison helpers.
std::encoding::base64	2	RFC 4648 base64 encode/decode.
std::encoding::binary	2	Big-endian / little-endian integer packing.
std::encoding::hex	2	Lowercase hex encode/decode.
std::encoding::json	6	JSON parser, emitter, and derive support.
std::errors	6	Error construction, wrapping, and chain traversal.
std::flag	2	Batteries-included CLI argument parsing.
std::fmt	9	Formatted printing and string interpolation.
std::fs	6	Filesystem walking and mutation helpers.
std::http	8	HTTP/1.1 client and server.
std::io	8	Stream-oriented I/O abstractions.
std::math::rand	1	Deterministic pseudo-random number generation.
std::net	4	TCP/UDP networking primitives.
std::net::url	3	URL parsing, rendering, and query escaping.
std::os	15	Operating-system primitives: filesystem, env, process.
std::os::exec	5	Spawn / wait for child processes (Go's os/exec shape).
std::os::signal	4	POSIX-style signal subscription (Go's os/signal shape).
std::panic	2	Panic / catch_unwind integration.
std::path	6	POSIX-style path manipulation.
std::path::native	5	Native-separator wrappers over std::path (backslash on Windows).
std::regex	10	Compiled regular expressions (Rust regex crate syntax; no backreferences or look-around).
std::runtime	4	Goroutine / GC / scheduler introspection and tuning.
std::slog	4	Structured, levelled logging.
std::sort	3	Slice sorting and binary search.
std::strconv	6	Conversions between strings and primitive numeric types.
std::strings	10	Polished String operations.
std::sync	8	Synchronisation primitives beyond channels.
std::testing	3	Assertions and sub-test harness helpers.
std::time	5	Wall-clock and monotonic time facilities.
std::tls	5	TLS termination and TLS client dialling (rustls-backed; not yet wired).
std::utf8	2	UTF-8 validation and scalar decoding.

std::bufio¶

Buffered readers, writers, and line scanners.

Item	Kind	Doc
Reader	type	Buffered reader.
Scanner	type	Line / token scanner.
Writer	type	Buffered writer.

std::bytes¶

Byte buffers, builders, and slice helpers.

Item	Kind	Doc
Buffer	type	Growable byte buffer.
Builder	type	Incremental string builder.
index_of	fn	First occurrence of a byte needle.
replace	fn	Replaces every occurrence of a byte needle.
split	fn	Splits on every separator occurrence.

std::collections¶

Built-in container types.

Item	Kind	Doc
BTreeMap	type	Ordered map.
BTreeSet	type	Ordered set built on top of BTreeMap.
HashMap	type	Hash map backed by the swiss-table layout.
HashSet	type	Unordered set built on top of HashMap.
Vec	type	Growable contiguous sequence.
VecDeque	type	Double-ended queue backed by a ring buffer.

std::compress::gzip¶

gzip encoder / decoder (RFC 1952; flate2-backed).

Item	Kind	Doc
Level	type	Compression level (0 store-only … 9 best); default is gzip(1)'s 6.
decode	fn	Decompresses a gzip-formatted payload.
encode	fn	Compresses bytes at the supplied Level.

std::context¶

Request-scoped cancellation, deadlines, and timeouts.

Item	Kind	Doc
Context	type	Cancellation-aware context handle.
background	fn	Root context — never cancelled.
with_cancel	fn	Child context plus explicit cancel handle.
with_deadline	fn	Child context that cancels at the supplied instant.
with_timeout	fn	Child context that cancels after the supplied duration.

std::crypto::hmac¶

HMAC-SHA-256 keyed MACs.

Item	Kind	Doc
sha256_mac	fn	HMAC-SHA-256 over a message.

std::crypto::rand¶

Secure random bytes from the host CSPRNG.

Item	Kind	Doc
bytes	fn	Returns a fresh random byte vector.
fill	fn	Fills a buffer with random bytes.

std::crypto::sha256¶

SHA-256 hashing.

Item	Kind	Doc
digest	fn	Returns the 32-byte digest of an input.
hex	fn	Returns the digest as lowercase hex.

std::crypto::subtle¶

Constant-time comparison helpers.

Item	Kind	Doc
constant_time_eq	fn	Compares two byte slices without data-dependent branches.

std::encoding::base64¶

RFC 4648 base64 encode/decode.

Item	Kind	Doc
decode	fn	Decodes a base64 string.
encode	fn	Encodes bytes to a base64 string.

std::encoding::binary¶

Big-endian / little-endian integer packing.

Item	Kind	Doc
put_u16_be	fn	Writes a big-endian u16.
put_u32_be	fn	Writes a big-endian u32.

std::encoding::hex¶

Lowercase hex encode/decode.

Item	Kind	Doc
decode	fn	Decodes a hex string.
encode	fn	Encodes bytes to hex.

std::encoding::json¶

JSON parser, emitter, and derive support.

Item	Kind	Doc
Error	type	Error raised by encoding/decoding operations.
Value	type	Dynamically typed JSON value.
Deserialize	trait	Trait for parsing a value from JSON.
Serialize	trait	Trait for converting a value to JSON.
decode	fn	Decodes a JSON String into a Deserialize value.
encode	fn	Encodes a Serialize value as a JSON String.

std::errors¶

Error construction, wrapping, and chain traversal.

Item	Kind	Doc
Error	type	Reference-counted error value with optional cause chain.
chain	fn	Iterator over an error and its ancestor causes.
is	fn	Checks whether an error's chain contains a matching message.
join	fn	Joins a list of errors into a single piped error.
new	fn	Constructs a fresh error from a message.
wrap	fn	Wraps a cause with a higher-level message.

std::flag¶

Batteries-included CLI argument parsing.

Item	Kind	Doc
Error	type	Error produced while parsing flags.
Set	type	Flag definition + parsing set.

std::fmt¶

Formatted printing and string interpolation.

Item	Kind	Doc
Debug	trait	Trait for debugging-oriented string conversion.
Display	trait	Trait for human-readable string conversion.
eprint	macro	Prints to stderr without a trailing newline.
eprintln	macro	Prints to stderr followed by a newline.
format	macro	Formats arguments into an owned String.
print	macro	Prints to stdout without a trailing newline.
println	macro	Prints to stdout followed by a newline.
write	macro	Writes formatted output into a Writer.
writeln	macro	Writes formatted output into a Writer followed by a newline.

std::fs¶

Filesystem walking and mutation helpers.

Item	Kind	Doc
copy	fn	Copies a file, creating parent dirs as needed.
create_dir_all	fn	Creates a path and any missing ancestors.
read_dir	fn	Returns the immediate children of a directory.
remove_all	fn	Deletes a file or a directory tree.
rename	fn	Renames a file or directory.
walk_dir	fn	Recursively visits every descendant entry.

std::http¶

HTTP/1.1 client and server.

Item	Kind	Doc
Client	type	HTTP client capable of GET/POST/PUT/DELETE.
Headers	type	Case-insensitive header map.
Method	type	HTTP method enumeration.
Request	type	HTTP request value passed to a handler.
Response	type	HTTP response value returned from a handler.
Server	type	HTTP server bound to a TCP listener.
StatusCode	type	HTTP status code.
serve	fn	Convenience: bind and serve an HTTP handler.

std::io¶

Stream-oriented I/O abstractions.

Item	Kind	Doc
BufReader	type	Buffered wrapper around any Reader.
BufWriter	type	Buffered wrapper around any Writer.
Error	type	Errors raised by I/O operations.
Reader	trait	Pull-style byte source.
Writer	trait	Push-style byte sink.
stderr	fn	Returns a handle to the process's standard error stream.
stdin	fn	Returns a handle to the process's standard input stream.
stdout	fn	Returns a handle to the process's standard output stream.

std::math::rand¶

Deterministic pseudo-random number generation.

Item	Kind	Doc
Rng	type	SplitMix64-based RNG.

std::net¶

TCP/UDP networking primitives.

Item	Kind	Doc
TcpListener	type	Accepts incoming TCP connections.
TcpStream	type	Bidirectional TCP byte stream.
UdpSocket	type	Bound UDP socket for datagram I/O.
resolve	fn	Resolves a hostname to a list of IP addresses.

std::net::url¶

URL parsing, rendering, and query escaping.

Item	Kind	Doc
Url	type	Parsed URL.
query_escape	fn	Percent-encodes a query parameter.
query_unescape	fn	Inverse of query_escape.

std::os¶

Operating-system primitives: filesystem, env, process.

Item	Kind	Doc
File	type	Open file handle supporting read/write/seek/close.
args	fn	Returns the program's command-line arguments.
create	fn	Creates or truncates a file for writing.
env	fn	Returns the value of an environment variable.
exists	fn	Returns whether a path exists.
exit	fn	Exits the process with the given status code.
mkdir	fn	Creates a single directory.
mkdir_all	fn	Creates a directory and any required parents.
open	fn	Opens a file for reading.
read_dir	fn	Iterates the entries of a directory.
read_file	fn	Reads an entire file into memory.
remove_file	fn	Removes a file from the filesystem.
rename	fn	Renames a file or directory.
set_env	fn	Sets an environment variable in the current process.
write_file	fn	Writes the given bytes to a file, creating it if needed.

std::os::exec¶

Spawn / wait for child processes (Go's os/exec shape).

Item	Kind	Doc
Child	type	Handle to a still-running child supporting wait / kill.
Command	type	Builder for spawning a child process.
ExitStatus	type	Numeric exit code (None when killed by signal).
Output	type	Captured stdout, stderr, and exit status from a finished child.
Stdio	type	Inherit / Piped / Null wiring for stdin/stdout/stderr.

std::os::signal¶

POSIX-style signal subscription (Go's os/signal shape).

Item	Kind	Doc
Notifier	type	Returned by on(sig); supports wait / try_wait.
Signal	type	Opaque signal name; constructors live in sigs.
deliver	fn	Test helper: synthesise a signal delivery without involving the OS.
on	fn	Subscribes to a signal; returns a Notifier.

std::panic¶

Panic / catch_unwind integration.

Item	Kind	Doc
catch_unwind	fn	Runs a closure, catching any panic it raises.
panic	macro	Aborts the current goroutine with a message.

std::path¶

POSIX-style path manipulation.

Item	Kind	Doc
base	fn	Final path segment.
clean	fn	Collapses ., .., and duplicate separators.
dir	fn	Directory portion.
ext	fn	Dotted extension, if any.
join	fn	Joins two path fragments.
split	fn	Returns (dir, file) for the supplied path.

std::path::native¶

Native-separator wrappers over std::path (backslash on Windows).

Item	Kind	Doc
clean	fn	Canonicalises a path into native-separator form.
join	fn	Joins two components using the platform separator.
to_native	fn	Rewrites a posix path into native-separator form.
to_posix	fn	Rewrites a native-separator path into posix form.
SEPARATOR	const	Platform-preferred path separator character.

std::regex¶

Compiled regular expressions (Rust regex crate syntax; no backreferences or look-around).

Item	Kind	Doc
Pattern	type	Compiled pattern handle returned by compile.
captures	fn	Returns capture groups for the first match; index 0 is the full match.
captures_all	fn	Returns capture groups for every match in the text.
compile	fn	Parses a pattern into a reusable Pattern or returns an Err.
find	fn	Returns the first match as (start, end, text), or None.
find_all	fn	Returns every non-overlapping match as (start, end, text).
is_match	fn	Returns whether the pattern matches anywhere in the text.
replace	fn	Replaces the first match with the given replacement (supports $N).
replace_all	fn	Replaces every non-overlapping match.
split	fn	Splits the text on every pattern match.

std::runtime¶

Goroutine / GC / scheduler introspection and tuning.

Item	Kind	Doc
max_procs	fn	Returns the current goroutine concurrency cap.
mem_stats	fn	Read-only snapshot of GC and allocation counters.
num_cpus	fn	Logical CPU cores visible to the process.
set_max_procs	fn	Sets the goroutine concurrency cap (GOMAXPROCS-equivalent).

std::slog¶

Structured, levelled logging.

Item	Kind	Doc
Field	type	Key/value pair threaded through a logger.
JsonHandler	type	JSON-lines handler.
Logger	type	Logger handle.
TextHandler	type	Line-oriented handler.

std::sort¶

Slice sorting and binary search.

Item	Kind	Doc
binary_search	fn	Binary search on a sorted slice.
sort	fn	Ascending unstable sort.
sort_stable	fn	Ascending stable sort.

std::strconv¶

Conversions between strings and primitive numeric types.

Item	Kind	Doc
format_f64	fn	Renders an f64 as a decimal string.
format_i64	fn	Renders an i64 as a decimal string.
parse_bool	fn	Parses "true" / "false" into a bool.
parse_f64	fn	Parses a decimal f64.
parse_i64	fn	Parses a decimal i64.
parse_u64	fn	Parses a decimal u64.

std::strings¶

Polished String operations.

Item	Kind	Doc
contains	fn	Returns whether the string contains a substring.
ends_with	fn	Returns whether the string ends with the given suffix.
find	fn	Returns the byte position of the first match.
replace	fn	Replaces every occurrence of from with to.
split	fn	Splits a string by a delimiter.
splitn	fn	Splits a string into at most n parts.
starts_with	fn	Returns whether the string starts with the given prefix.
to_lowercase	fn	Lowercases every character.
to_uppercase	fn	Uppercases every character.
trim	fn	Removes leading and trailing whitespace.

std::sync¶

Synchronisation primitives beyond channels.

Item	Kind	Doc
AtomicBool	type	Atomic boolean.
AtomicI64	type	Atomic 64-bit signed integer.
AtomicU64	type	Atomic 64-bit unsigned integer.
Barrier	type	Synchronisation barrier across goroutines.
Mutex	type	Mutual-exclusion lock.
Once	type	One-shot initialisation latch.
RwLock	type	Reader-writer lock.
WaitGroup	type	Counts goroutines and waits for them to finish.

std::testing¶

Assertions and sub-test harness helpers.

Item	Kind	Doc
Runner	type	Sub-test collector.
check	fn	Asserts a condition.
check_eq	fn	Asserts equality, rendering a diff on failure.

std::time¶

Wall-clock and monotonic time facilities.

Item	Kind	Doc
Duration	type	Difference between two Instants.
Instant	type	Monotonic point-in-time.
SystemTime	type	Wall-clock point-in-time.
now	fn	Returns the current monotonic Instant.
sleep	fn	Suspends the current goroutine for Duration.

std::tls¶

TLS termination and TLS client dialling (rustls-backed; not yet wired).

Item	Kind	Doc
CertKey	type	PEM-encoded certificate chain + private key.
ClientConfig	type	Opaque client-side TLS configuration.
ServerConfig	type	Opaque server-side TLS configuration.
client_config	fn	Builds a client config. Returns Err until rustls lands.
server_config	fn	Builds a server config from a CertKey. Returns Err until rustls lands.

std::utf8¶

UTF-8 validation and scalar decoding.

Item	Kind	Doc
is_valid	fn	Validates a byte slice as UTF-8.
rune_count	fn	Counts Unicode scalar values.