fernctl/ports/mod.rs
1//! # Ports — Hexagonal Architecture Interfaces
2//!
3//! This module defines the **ports** in fernctl's hexagonal architecture.
4//! Ports are trait-based interfaces that decouple the domain logic from
5//! external systems, enabling testability and flexibility.
6//!
7//! ## What are Ports?
8//!
9//! In hexagonal architecture (also known as "ports and adapters"), ports are
10//! the interfaces through which the application core communicates with the
11//! outside world. They define *what* operations are available without
12//! specifying *how* those operations are implemented.
13//!
14//! ```text
15//! ┌─────────────────────────────────────────────────────────────────────┐
16//! │ EXTERNAL WORLD │
17//! │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
18//! │ │ TOML Files │ │ CLI │ │ D-Bus │ │
19//! │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
20//! │ │ │ │ │
21//! │ ┌─────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐ │
22//! │ │TomlAdapter │ │ CliAdapter │ │DbusAdapter │ ← ADAPTERS │
23//! │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
24//! └─────────┼─────────────────┼─────────────────┼───────────────────────┘
25//! │ │ │
26//! ╔═════╧═════════════════╧═════════════════╧═════╗
27//! ║ INBOUND PORTS ║
28//! ║ ConfigPort, ValidatePort, QueryPort ║ ← INTERFACES
29//! ╚═════════════════════╤═════════════════════════╝
30//! │
31//! ┌─────────────────────▼─────────────────────────┐
32//! │ DOMAIN │
33//! │ Theme, Tokens, Validation │ ← PURE LOGIC
34//! └─────────────────────┬─────────────────────────┘
35//! │
36//! ╔═════════════════════╧═════════════════════════╗
37//! ║ OUTBOUND PORTS ║
38//! ║ PersistPort, NotifyPort, IpcPort ║ ← INTERFACES
39//! ╚═════╤═════════════════╤═════════════════════╤═╝
40//! │ │ │
41//! ┌─────────┼─────────────────┼─────────────────────┼───────────────────┐
42//! │ ┌─────▼──────┐ ┌─────▼──────┐ ┌─────────▼────┐ │
43//! │ │FileAdapter │ │NotifAdapter│ │QuickShellIpc │ ← ADAPTERS │
44//! │ └─────┬──────┘ └─────┬──────┘ └─────────┬────┘ │
45//! │ │ │ │ │
46//! │ ┌─────▼──────┐ ┌─────▼──────┐ ┌─────────▼────┐ │
47//! │ │ File System│ │ D-Bus Notif│ │ QuickShell │ │
48//! │ └────────────┘ └────────────┘ └──────────────┘ │
49//! │ EXTERNAL WORLD │
50//! └─────────────────────────────────────────────────────────────────────┘
51//! ```
52//!
53//! ## Inbound vs Outbound
54//!
55//! Ports are divided into two categories based on the direction of dependency:
56//!
57//! | Category | Direction | Purpose | Examples |
58//! |----------|-----------|---------|----------|
59//! | **Inbound** | External → Domain | Drive the application | Load config, validate, query |
60//! | **Outbound** | Domain → External | Use external services | Save files, send notifications |
61//!
62//! ### Inbound Ports ([`inbound`])
63//!
64//! Inbound ports define how external systems can *drive* the application.
65//! They are implemented by **adapters** that translate external requests
66//! into domain operations.
67//!
68//! ```rust,ignore
69//! // A TOML adapter implements ConfigPort
70//! impl ConfigPort for TomlConfigAdapter {
71//! fn load(&self, source: &str) -> Result<RawConfig> {
72//! // Parse TOML and return domain types
73//! }
74//! }
75//! ```
76//!
77//! ### Outbound Ports ([`outbound`])
78//!
79//! Outbound ports define how the domain can *use* external services.
80//! They are implemented by **adapters** that translate domain requests
81//! into external operations.
82//!
83//! ```rust,ignore
84//! // A file adapter implements PersistPort
85//! impl PersistPort for FileSystemAdapter {
86//! fn save(&self, path: &Path, theme: &Theme) -> Result<()> {
87//! // Serialize theme and write to file
88//! }
89//! }
90//! ```
91//!
92//! ## Why This Architecture?
93//!
94//! The hexagonal architecture provides several benefits:
95//!
96//! ### 1. Testability
97//!
98//! The domain can be tested in isolation using mock adapters:
99//!
100//! ```rust,ignore
101//! struct MockNotifyPort;
102//! impl NotifyPort for MockNotifyPort {
103//! fn send(&self, notification: Notification) -> Result<()> {
104//! // Just record the call, don't actually send
105//! Ok(())
106//! }
107//! }
108//!
109//! #[test]
110//! fn domain_sends_notification_on_error() {
111//! let notifier = MockNotifyPort;
112//! // Test domain logic with mock
113//! }
114//! ```
115//!
116//! ### 2. Flexibility
117//!
118//! Adapters can be swapped without changing domain logic:
119//!
120//! ```rust,ignore
121//! // Development: Use file-based config
122//! let config_port: Box<dyn ConfigPort> = Box::new(TomlConfigAdapter::new());
123//!
124//! // Testing: Use in-memory config
125//! let config_port: Box<dyn ConfigPort> = Box::new(InMemoryConfigAdapter::new());
126//! ```
127//!
128//! ### 3. Separation of Concerns
129//!
130//! Each layer has a clear responsibility:
131//!
132//! - **Domain**: Business rules and design system logic
133//! - **Ports**: Interface contracts
134//! - **Adapters**: External system integration
135//!
136//! ## Module Organization
137//!
138//! - [`inbound`] — Ports for driving the application (config loading, validation, queries)
139//! - [`outbound`] — Ports for driven services (persistence, notifications, IPC)
140//!
141//! ## Design Principles
142//!
143//! Ports in fernctl follow these principles:
144//!
145//! 1. **Trait-based** — All ports are Rust traits, enabling static dispatch
146//! when possible and dynamic dispatch when flexibility is needed.
147//!
148//! 2. **Error-aware** — All fallible operations return `Result<T, FernError>`,
149//! ensuring errors are handled explicitly.
150//!
151//! 3. **Domain-typed** — Ports work with domain types (`Theme`, `Notification`),
152//! not external representations (raw JSON, D-Bus messages).
153//!
154//! 4. **Object-safe** — Ports are designed to be object-safe where possible,
155//! enabling use as trait objects (`Box<dyn ConfigPort>`).
156
157pub mod inbound;
158pub mod outbound;
159
160// Re-export primary traits for convenience
161pub use inbound::{ConfigPort, QueryPort, ValidatePort};
162pub use outbound::{IpcPort, NotifyPort, PersistPort};