grafos_std/
fabric.rs

1//! Discovery and allocation entry point for fabric resources.
2//!
3//! The [`Fabric`] struct is the top-level entry point for programs that
4//! need to discover available nodes and allocate resources across the
5//! fabric. It provides builder methods for all resource types (memory,
6//! block, GPU, CPU).
7//!
8//! # Example
9//!
10//! ```rust
11//! use grafos_std::fabric::Fabric;
12//! use grafos_std::mem::MemBuilder;
13//!
14//! # grafos_std::host::reset_mock();
15//! # grafos_std::host::mock_set_fbmu_arena_size(65536);
16//! let fabric = Fabric::connect("10.10.0.11:5701")?;
17//!
18//! // Discover nodes (returns empty list until host discovery API is added)
19//! let nodes = fabric.nodes();
20//!
21//! // Allocate memory via the fabric entry point
22//! let lease = fabric.alloc_mem().min_bytes(4096).acquire()?;
23//! lease.mem().write(0, b"hello")?;
24//! # Ok::<(), grafos_std::FabricError>(())
25//! ```
26
27extern crate alloc;
28use alloc::string::String;
29use alloc::vec::Vec;
30
31use crate::block::BlockBuilder;
32use crate::cpu::CpuBuilder;
33use crate::error::Result;
34use crate::gpu::GpuBuilder;
35use crate::mem::MemBuilder;
36
37/// Information about a discovered fabric node.
38///
39/// Returned by [`Fabric::nodes`] as part of fabric discovery. Contains
40/// the node's network address for establishing data-plane connections.
41#[derive(Debug, Clone)]
42pub struct NodeInfo {
43    /// Node address in `host:port` format (e.g. `"10.10.0.11:5701"`).
44    pub addr: String,
45}
46
47/// Entry point for discovering and allocating fabric resources.
48///
49/// `Fabric` represents a connection to the fabric control plane. Use it
50/// to discover available nodes and create resource allocation builders.
51///
52/// In WASM, the connection is managed by the host runtime. On native
53/// targets, the address is recorded for use in future host function
54/// implementations.
55///
56/// # Examples
57///
58/// ```rust
59/// use grafos_std::fabric::Fabric;
60///
61/// # grafos_std::host::reset_mock();
62/// # grafos_std::host::mock_set_fbmu_arena_size(65536);
63/// # grafos_std::host::mock_set_fbbu_num_blocks(1024);
64/// let fabric = Fabric::connect("10.10.0.11:5701")?;
65///
66/// // Access resource builders
67/// let _mem = fabric.alloc_mem();
68/// let _blk = fabric.alloc_block();
69/// let _gpu = fabric.alloc_gpu();
70/// let _cpu = fabric.alloc_cpu();
71/// # Ok::<(), grafos_std::FabricError>(())
72/// ```
73pub struct Fabric {
74    _addr: String,
75}
76
77impl Fabric {
78    /// Connect to the fabric at the given address.
79    ///
80    /// In WASM, the connection is managed by the host runtime — the
81    /// address is passed through to the host. On native targets, this
82    /// records the address for future use and always succeeds.
83    ///
84    /// # Errors
85    ///
86    /// Currently infallible. Will return [`crate::FabricError::Disconnected`]
87    /// once real connection logic is implemented.
88    pub fn connect(addr: &str) -> Result<Fabric> {
89        Ok(Fabric {
90            _addr: String::from(addr),
91        })
92    }
93
94    /// Discover available nodes in the fabric.
95    ///
96    /// Returns a list of [`NodeInfo`] structs for each discovered node.
97    /// Returns an empty list until the host provides a discovery function.
98    pub fn nodes(&self) -> Vec<NodeInfo> {
99        Vec::new()
100    }
101
102    /// Start building a memory allocation request.
103    ///
104    /// Returns a [`MemBuilder`] that can be configured with capacity
105    /// requirements before calling [`acquire`](MemBuilder::acquire).
106    pub fn alloc_mem(&self) -> MemBuilder {
107        MemBuilder::new()
108    }
109
110    /// Start building a block storage allocation request.
111    ///
112    /// Returns a [`BlockBuilder`] that can be configured with capacity
113    /// requirements before calling [`acquire`](BlockBuilder::acquire).
114    pub fn alloc_block(&self) -> BlockBuilder {
115        BlockBuilder::new()
116    }
117
118    /// Start building a GPU allocation request.
119    ///
120    /// Returns a [`GpuBuilder`] that can be configured with VRAM
121    /// requirements before calling [`acquire`](GpuBuilder::acquire).
122    pub fn alloc_gpu(&self) -> GpuBuilder {
123        GpuBuilder::new()
124    }
125
126    /// Start building a CPU allocation request.
127    ///
128    /// Returns a [`CpuBuilder`] that can be configured with core count
129    /// and lease duration before calling [`acquire`](CpuBuilder::acquire).
130    pub fn alloc_cpu(&self) -> CpuBuilder {
131        CpuBuilder::new()
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    #[test]
140    fn fabric_connect_and_discover() {
141        let fabric = Fabric::connect("10.10.0.11:5701").expect("connect");
142        let nodes = fabric.nodes();
143        // Discovery is not yet implemented; empty list is expected.
144        assert!(nodes.is_empty());
145    }
146
147    #[test]
148    fn fabric_alloc_builders_are_accessible() {
149        let fabric = Fabric::connect("localhost").expect("connect");
150        // These should compile and return builders.
151        let _mem = fabric.alloc_mem();
152        let _blk = fabric.alloc_block();
153        let _gpu = fabric.alloc_gpu();
154        let _cpu = fabric.alloc_cpu();
155    }
156}
grafos_std/fabric.rs

grafos_std/
fabric.rs
