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};