lava_flow/
error.rs

1use thiserror::Error;
2
3/// Shared validation reasons reused across public API errors.
4#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
5pub enum ValidationReason {
6    /// The provided value was empty.
7    #[error("must not be empty")]
8    Empty,
9
10    /// The provided identifier exceeded the identifier length limit.
11    #[error("must be at most 64 characters")]
12    IdentifierTooLong,
13
14    /// The provided hostname exceeded the hostname length limit.
15    #[error("must be at most 253 characters")]
16    HostnameTooLong,
17
18    /// The first character was not allowed.
19    #[error("must start with an ASCII letter or digit")]
20    InvalidStartCharacter,
21
22    /// One or more characters were outside the allowed identifier charset.
23    #[error("must contain only lowercase ASCII letters, digits, '-' or '_'")]
24    InvalidCharacters,
25}
26
27/// Shared reasons for allocation request failures.
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
29pub enum AllocationReason {
30    /// The requested size was zero.
31    #[error("allocation size must be greater than zero")]
32    ZeroSize,
33    /// The requested size exceeded the current allocation limit.
34    #[error("allocation size exceeds maximum supported size")]
35    ExceedsMaxSize,
36}
37
38/// Top-level error type for lava-flow core APIs.
39#[derive(Debug, Error)]
40pub enum LavaFlowError {
41    /// Process name validation failed.
42    #[error("invalid process name `{value}`: {reason}")]
43    InvalidProcessName {
44        /// The original rejected input.
45        value: String,
46        /// Structured reason for rejection.
47        reason: ValidationReason,
48    },
49
50    /// Channel ID validation failed.
51    #[error("invalid channel id `{value}`: {reason}")]
52    InvalidChannelId {
53        /// The original rejected input.
54        value: String,
55        /// Structured reason for rejection.
56        reason: ValidationReason,
57    },
58
59    /// Hostname validation failed.
60    #[error("invalid hostname `{value}`: {reason}")]
61    InvalidHostname {
62        /// The original rejected input.
63        value: String,
64        /// Structured reason for rejection.
65        reason: ValidationReason,
66    },
67
68    /// Hostname detection via OS APIs failed.
69    #[error("failed to detect local hostname")]
70    HostnameDetection(#[source] std::io::Error),
71
72    /// Memory allocation request failed validation.
73    #[error("invalid allocation request (size={size}): {reason}")]
74    InvalidAllocationRequest {
75        /// Requested allocation size in bytes.
76        size: usize,
77        /// Structured reason for rejection.
78        reason: AllocationReason,
79    },
80
81    /// A requested GPU device id is not known by the allocator.
82    #[error("GPU device `{device_id}` not found")]
83    GpuDeviceNotFound {
84        /// Requested device id.
85        device_id: u32,
86    },
87
88    /// Interprocess handle kind is not supported for the requested operation.
89    #[error("unsupported interprocess handle for operation: {kind}")]
90    UnsupportedInterprocessHandle {
91        /// Handle kind string for diagnostics.
92        kind: &'static str,
93    },
94
95    /// GPU allocation was requested but no GPU backend is available.
96    #[error("GPU backend is not available")]
97    GpuBackendUnavailable,
98
99    /// Vulkan backend operation failed.
100    #[error("vulkan operation failed during {operation}: {details}")]
101    VulkanOperation {
102        /// Vulkan operation name.
103        operation: &'static str,
104        /// Human-readable details, typically a Vulkan result code.
105        details: String,
106    },
107
108    /// Internal allocator state lock was poisoned by a prior panic.
109    #[error("allocator state lock poisoned: {component}")]
110    AllocatorStatePoisoned {
111        /// Internal component that failed lock acquisition.
112        component: &'static str,
113    },
114
115    /// OS shared-memory operation failed.
116    #[error("shared memory operation failed during {operation}")]
117    SharedMemoryOperation {
118        /// Shared-memory operation name.
119        operation: &'static str,
120        /// Source OS error.
121        #[source]
122        source: std::io::Error,
123    },
124
125    /// Channel metadata serialization or deserialization failed.
126    #[error("channel metadata codec failed during {operation}")]
127    ChannelMetadataCodec {
128        /// Metadata codec operation name.
129        operation: &'static str,
130        /// Source serialization error.
131        #[source]
132        source: serde_json::Error,
133    },
134
135    /// Requested channel metadata encoding is not implemented.
136    #[error("unsupported metadata encoding: {encoding}")]
137    UnsupportedMetadataEncoding {
138        /// Human-readable encoding name.
139        encoding: &'static str,
140    },
141
142    /// Channel transport I/O failed during a platform operation.
143    #[error("channel transport operation failed during {operation}")]
144    ChannelTransportOperation {
145        /// Transport operation name.
146        operation: &'static str,
147        /// Source I/O error.
148        #[source]
149        source: std::io::Error,
150    },
151
152    /// Channel transport was disconnected before the operation completed.
153    #[error("channel transport disconnected")]
154    ChannelDisconnected,
155
156    /// Channel buffer kind is not supported by the selected transport.
157    #[error("unsupported channel buffer kind: {kind}")]
158    UnsupportedChannelBufferKind {
159        /// Buffer kind string for diagnostics.
160        kind: &'static str,
161    },
162}
163
164/// Standard result type for lava-flow APIs.
165pub type Result<T> = std::result::Result<T, LavaFlowError>;
lava_flow/error.rs

lava_flow/
error.rs
