System & Network Libraries
Relevant source files
The following files were used as context for generating this wiki page:
- architecture/22.2-system-network-security-catalog.md
- architecture/22.6-standard-library-implementation-plan.md
- architecture/decisions/0031-public-library-tiers-and-names.md
- architecture/decisions/0032-concise-apis-and-cost-contracts.md
- architecture/20-xml-documentation-comments.md
- crates/tools/architecture-tests/src/tests.rs
The System & Network Libraries in Pop Lang constitute a structured collection of foundational and extension Bubbles designed to provide high-performance, portable, and secure access to host operating system capabilities and network protocols. These libraries are partitioned into distinct "tiers" and "families," ensuring that core portable functionality remains separated from platform-specific or heavy-weight network stacks.
The architecture emphasizes a "function-first" approach, utilizing immutable records, typed protocols, and explicit resource handles. This design avoids traditional Object-Oriented patterns in favor of concise call sites and explicit cost contracts, ensuring developers can reason about allocation, blocking, and complexity directly from the API.
Sources: architecture/22.2-system-network-security-catalog.md, architecture/decisions/0032-concise-apis-and-cost-contracts.md:10-18
Library Architecture and Tiers
The Pop Lang library ecosystem follows a strict ownership hierarchy: Item → Module → Bubble → Package → Workspace. System and network functionalities are distributed across these units based on their portability and resource requirements.
Distribution Tiers
Libraries are categorized into three primary tiers to manage dependencies and platform constraints:
| Tier | Description | Included Families (Partial List) |
|---|---|---|
| Foundation | Portable, core logic present in every Pop environment. | Io, Path, Process, Environment |
| Platform | Native OS-specific capabilities; availability varies by target. | Platform, Terminal, Archive, Compress |
| Extension | Independently versioned packages for specialized domains. | Net, Http, Crypto, Socket |
Sources: architecture/22.6-standard-library-implementation-plan.md:12-21, architecture/decisions/0031-public-library-tiers-and-names.md:14-22
Dependency and Data Flow
The following diagram illustrates the relationship between the foundational Io systems and higher-level network extensions.
The diagram shows how core Io and Bytes form the basis for Net and Http extensions.
Sources: architecture/22.6-standard-library-implementation-plan.md:14-21, architecture/decisions/0031-public-library-tiers-and-names.md:14-22
System Libraries
System libraries provide the interface between Pop Lang code and the host environment. These are designed to be "capability-aware," meaning they explicitly report unsupported behaviors on restricted targets.
Io and Path
The Io family defines the protocols for reading and writing data. It prioritizes "caller-owned buffers" to allow for zero-allocation data processing.
- Io.Path: Handles lexical path manipulation independently of the filesystem.
- File/Directory: Provides the actual OS-backed operations for persistence.
Process and Environment
These modules manage host interaction:
- Process: Handles execution, signals, and process lifecycle.
- Environment: Manages environment variables and host-provided configuration.
- Platform: Exposes target-specific metadata and capabilities.
Sources: architecture/22.6-standard-library-implementation-plan.md:17-19, architecture/decisions/0032-concise-apis-and-cost-contracts.md:47-51
Network & Security Libraries
Network libraries are typically implemented as Official Extension Packages to prevent forcing network stack dependencies on small, non-networked applications.
Structured Concurrency and Networking
Networking in Pop Lang is built on Structured Concurrency. Operations like Socket.connect or Http.send are designed to integrate with Task groups for cancellation and deadline management.
This diagram demonstrates the flow of a network connection task and the use of result-based error handling.
Sources: architecture/22.6-standard-library-implementation-plan.md:20-21, architecture/decisions/0032-concise-apis-and-cost-contracts.md:52-54
Security and Cryptography
Security is handled through the Crypto and Tls families. The library architecture mandates that no sensitive data (like credentials) enters diagnostics or cache keys.
- Crypto: Provides primitives for hashing and encryption.
- Net.Tls: Implements secure transport protocols, depending on both
NetandCrypto.
Sources: architecture/22.2-system-network-security-catalog.md, architecture/22.6-standard-library-implementation-plan.md:20-21
API Cost and Contracts
A defining feature of these libraries is the Explicit Cost Contract. Every public API must document its behavior regarding resource usage.
| Contract Element | Requirement |
|---|---|
| Allocation | Must state if the call allocates on the heap. |
| Dispatch | Distinguishes between direct calls and indirect (interface) dispatch. |
| Blocking | Explicitly marks if a function blocks the thread or suspends the task. |
| Native Boundary | Identifies transitions into the Pop Lang Runtime Interface (PLRI) or host syscalls. |
Sources: architecture/decisions/0032-concise-apis-and-cost-contracts.md:21-30, architecture/20-xml-documentation-comments.md:100-115
Code Snippet: Cost Documentation
Documentation uses XML tags to communicate these contracts to the compiler and tooling.
--- <summary>
--- Reads from the filesystem.
--- </summary>
--- <effect kind="Blocks">
--- Waits for operating-system file I/O.
--- </effect>
--- <allocation>
--- Does not allocate when the destination has capacity.
--- </allocation>
public function read(path: Path, buffer: Bytes): Result<Int, IoError>
Sources: architecture/20-xml-documentation-comments.md:110-125, architecture/decisions/0032-concise-apis-and-cost-contracts.md:52-54
Summary
The System & Network Libraries provide a tiered, high-performance interface to the host and network. By utilizing structured concurrency, explicit cost contracts, and a modular extension model, Pop Lang ensures that system operations are both powerful and predictable. Foundational IO and Path logic provide the baseline for complex, secure network protocols implemented in extension packages.