http://localhost:3000 Thoughts on programming, software architecture, and technology en-us Tue, 03 Feb 2026 00:00:00 GMT http://localhost:3000/posts/2026-02-03-framework-boundaries-and-macro-hygiene http://localhost:3000/posts/2026-02-03-framework-boundaries-and-macro-hygiene Tue, 03 Feb 2026 00:00:00 GMT , Path(id): Path, ) -> Result> { let user = db.users().find(id).await?; Ok(Json(UserResponse::from(user))) } ``` The macro expands this into the actual axum route registration, extracting path parameters, handling state injection, wrapping errors in our standard envelope format. Standard framework stuff. But the expansion was generating variable names that could collide with the handler's own scope. If your handler happened to use certain common names for local bindings, type inference would break. Not with a clear error—with confusing messages about trait bounds and lifetime mismatches three layers deep in the inference chain. This only surfaced in production because production code is messier than tutorial code. Real handlers have more local variables, more complex control flow, more generic parameters in play. The "works in the README" version doesn't survive contact with actual engineering. ## The Real Problem The bug itself is fixable. The *category* of bug is what matters. When a framework macro generates code that makes assumptions about the caller's namespace, it's not just a hygiene violation—it's an architectural boundary violation. The macro is reaching across the abstraction layer and making decisions about things it shouldn't know about. This is the same category of problem that makes dependency injection frameworks in languages like Java and C# so hard to reason about. The framework stops being a tool you use and starts being an environment you exist inside. It has opinions about your internal structure, not just your public interface. Rust's macro hygiene rules exist specifically to prevent this. When you write a declarative macro, identifiers you introduce don't collide with identifiers in the caller's scope unless you explicitly use `$var:ident` to capture them. This is a *design constraint*, not just a safety feature. It enforces that the macro operates in its own namespace and interacts with the caller only through explicit parameters. Procedural macros can violate this more easily because they're generating raw token streams. You can emit any identifier you want. The compiler won't stop you from shadowing the caller's variables. This is power, and with power comes the responsibility to not be an asshole. ## The Tension But here's where it gets interesting: developers *expect* framework magic. The entire value proposition of frameworks like FastAPI, Rails, ASP.NET Core—they wire things up automatically. You write a function with the right signature, slap an attribute on it, and the framework figures out how to turn HTTP bytes into typed parameters and typed results back into HTTP bytes. That's *good* magic. That's the abstraction doing its job. So where's the line? I think it's this: **magic is acceptable when it operates on the public interface, unacceptable when it makes assumptions about the internal implementation.** A routing macro can look at your function signature and generate the glue code to extract path parameters. That's operating on the public interface—the function's type. It's information you're explicitly publishing. A routing macro should *not* be generating variable names that could collide with your function body's internal bindings. That's making assumptions about your implementation details—information you didn't publish. This maps directly to the Rust type system's philosophy. Public vs. private isn't just about visibility—it's about contracts. Your public API is what you promise to the outside world. Your private implementation is what you reserve the right to change. A framework that makes assumptions about your private implementation is violating the abstraction boundary. ## Production Changes Everything The reason this bug only surfaced in production is important. Tutorial code is clean. Tutorial code has one responsibility per function, minimal local state, straightforward control flow. Tutorial code is *pedagogically optimized*, not *engineering optimized*. Production code is a mess. It has edge cases and error handling and "TODO: refactor this" comments from three months ago. It has functions that grew beyond their original scope because the deadline was yesterday. It has generic parameters that seemed like a good idea at the time. And that mess is *fine*. That's what real software looks like. The problem is when your framework can't handle it. This is why I'm skeptical of frameworks that prioritize demo elegance over production robustness. If your framework only works cleanly in the examples, it's not a framework—it's a pitch deck. Rapina's philosophy is "90% of apps should require 10% of decisions." That means we need to work in the messy 90%, not just the clean 10%. It means when someone writes a handler function that's longer than it should be and has more local variables than is ideal, the framework doesn't break. It doesn't shadow their variables. It doesn't make their compile errors incomprehensible. ## The AI Era Angle There's another reason this matters now: AI coding assistants. LLMs are great at generating clean tutorial-style code. They're less great at understanding the implicit assumptions and hidden coupling in "magical" frameworks. When a framework has a lot of implicit behavior—names that get generated behind the scenes, types that get inferred through complex trait chains, macros that reach into your scope—the AI can't reason about it clearly. This isn't just a current limitation of LLMs. It's a fundamental property of implicit systems. If the behavior isn't in the code, it's not in the training data. If the coupling isn't visible in the tokens, the model can't learn it. Rapina's goal is to be AI-friendly by being *explicit*. Predictable structure, clear boundaries, minimal magic. When an AI generates a Rapina handler, it should be obvious what code gets generated by the macro and what code is user-written. The boundary should be clear in the token stream. This is the same property that makes code maintainable by humans. Explicitness aids reasoning. Rust enforces explicitness through its type system and ownership model. Frameworks should extend that philosophy, not undermine it. ## What I Changed The fix we shipped today does three things: 1. **Prefixed all generated identifiers** with `__rapina_` to prevent collisions with user code 2. **Minimized the expansion scope** so generated bindings are introduced only where they're needed, not at the function level 3. **Added hygiene tests** that intentionally use common variable names in handlers to catch future violations But more importantly, we documented the principle: **Rapina macros operate on function signatures, not function bodies.** This is now a design constraint, not just a bug fix. If we need information from inside the function, we require it to be expressed in the signature—through parameters, return types, or explicit attributes. We don't reach in and assume. ## The Broader Pattern This maps to a pattern I've seen across systems at different scales: **the best abstractions are the ones that respect boundaries.** In distributed systems: services that communicate only through explicit contracts (APIs, message schemas) are more maintainable than services that share databases or internal implementation details. In type systems: functions that take explicit parameters are easier to reason about than functions that close over mutable state. In build systems: explicit dependencies in a manifest are better than implicit dependencies discovered at runtime. And in frameworks: macros that operate on public interfaces are better than macros that make assumptions about private implementation. Rust's ownership system enforces boundaries at the memory level. Its trait system enforces boundaries at the interface level. Framework design should extend this to the architectural level. ## What This Means for Technical Leadership If you're building frameworks, libraries, or any kind of abstraction layer, the question isn't "what can I make implicit?" It's "what *must* remain explicit to preserve the abstraction boundary?" Magic is seductive. Reducing boilerplate is genuinely valuable. But every implicit behavior is a tradeoff. You're trading explicitness for convenience, and the cost comes due when someone tries to debug the implicit behavior or extend it in ways you didn't anticipate. This is especially true in the AI era. The systems we build need to be *legible*—not just to humans, but to tools that operate on code as data. LLMs, static analyzers, refactoring tools—they all depend on being able to see the structure clearly. Rust gives us the tools to enforce this legibility: strong types, explicit lifetimes, hygiene rules in macros, the borrow checker. The question is whether we use them, or whether we work around them in pursuit of "better DX." I think the right answer is: use them. Lean into the constraints. Treat them as design guidance, not obstacles. The code that results is more robust, more maintainable, and more legible—to humans and machines alike. That's what architectural discipline means. Not just "writing clean code," but **designing systems where the boundaries are clear and enforced by the tools.** ## Conclusion We shipped to TestFlight today. The backend held up. The bug we found was real, but it was fixable, and more importantly, it was *findable*. It manifested as a compile-time error, not a runtime surprise. That's Rust doing its job. The fix we shipped makes the framework more disciplined. The boundary between framework and application is now clearer and more rigorously enforced. This makes the framework less magical, but more trustworthy. And in production, trustworthy beats magical every time. ]]> http://localhost:3000/posts/2026-01-27-when-the-type-system-justifies-deleting-process http://localhost:3000/posts/2026-01-27-when-the-type-system-justifies-deleting-process Tue, 27 Jan 2026 00:00:00 GMT http://localhost:3000/posts/2026-01-26-compile-time-boundaries-and-architectural-optionality http://localhost:3000/posts/2026-01-26-compile-time-boundaries-and-architectural-optionality Mon, 26 Jan 2026 00:00:00 GMT http://localhost:3000/posts/2026-01-23-building-sheen-bringing-charmbracelet-log-to-rust http://localhost:3000/posts/2026-01-23-building-sheen-bringing-charmbracelet-log-to-rust Fri, 23 Jan 2026 00:00:00 GMT bool { level >= self.level } ``` No manual comparisons, no match statements. The type system does the work. From there I built the `Logger` struct, added colors with `owo-colors`, then structured fields, timestamps, prefixes. Each feature small and incremental. ## Architecture decisions ### The Formatter trait At first, all formatting logic lived inside the `log()` method. It worked, but I knew adding JSON output would mean ugly if/else blocks everywhere. Not scalable. I wanted users to be able to swap formatters cleanly: ```rust let logger = Logger::new().formatter(JsonFormatter); ``` This meant introducing a trait: ```rust pub trait Formatter: Send + Sync { fn format( &self, level: Level, message: &str, timestamp: Option<&str>, prefix: Option<&str>, fields: &[(String, String)], extra: &[(&str, &dyn Debug)], ) -> String; } ``` The `Send + Sync` bounds are required because the global logger lives in a static and might be accessed from multiple threads. Rust forces you to think about this upfront. ### `Box` — dynamic dispatch I wanted to store any formatter in the Logger struct: ```rust pub struct Logger { level: Level, formatter: dyn Formatter, // ❌ won't compile } ``` The problem: `dyn Formatter` could be `TextFormatter` (0 bytes) or `JsonFormatter` (maybe 8 bytes) or some user's custom formatter. Rust needs to know struct sizes at compile time. The solution: `Box`. Box puts the data on the heap and stores a pointer (always 8 bytes on 64-bit): ```rust pub struct Logger { level: Level, formatter: Box, // ✅ always 8 bytes } ``` Think of it like storing a locker number instead of the actual item. The locker number always fits in your pocket, regardless of what's inside the locker. This is a classic Rust pattern for runtime polymorphism. The small overhead of heap allocation and dynamic dispatch is negligible for a logger. ### Ergonomic macros I wanted the API to feel natural: ```rust sheen::info!("Server started", port = 3000, host = "localhost"); ``` The macro: ```rust #[macro_export] macro_rules! info { ($msg:expr) => { $crate::global::logger().info($msg, &[]) }; ($msg:expr, $($key:ident = $value:expr),* $(,)?) => { $crate::global::logger().info( $msg, &[$(( stringify!($key), &$value as &dyn std::fmt::Debug )),*] ) }; } ``` `stringify!($key)` converts the identifier `port` to the string `"port"`. The repetition pattern `$(...),*` handles zero or more key=value pairs. The trailing `$(,)?` allows an optional trailing comma. ## Why sheen is a good project to learn Rust If you're looking to level up your Rust skills, building a logging library covers a lot of ground: **Traits and generics** — The Formatter trait teaches you how to design extensible APIs. You'll understand the difference between static dispatch (`impl Trait`) and dynamic dispatch (`dyn Trait`). **Ownership patterns** — `Box` for owned trait objects, `&dyn Debug` for borrowed trait objects. You'll learn when to use each. **Macros** — Declarative macros with `macro_rules!` are powerful. Building `info!`, `debug!`, etc. teaches pattern matching on syntax. **Builder pattern** — Idiomatic Rust configuration: ```rust Logger::new() .level(Level::Debug) .prefix("myapp") .timestamp(true) ``` **Global state** — Using `OnceLock` for safe, lazy initialization of a global logger. **TTY detection** — `std::io::IsTerminal` for smart behavior (colors in terminal, plain text when piped). The codebase is small enough to understand completely, but covers patterns you'll use in larger projects. ## What's next Features planned: - `log` crate compatibility — work with existing Rust ecosystem - Custom color themes - File output support - More time format options Check the [issues](https://github.com/arferreira/sheen/issues) — several are tagged `good first issue` if you want to contribute. ## Try it ```toml [dependencies] sheen = "0.2" ``` ```rust fn main() { sheen::init(); sheen::info!("Hello from sheen", version = "0.2.0"); } ``` - [GitHub](https://github.com/arferreira/sheen) - [Crates.io](https://crates.io/crates/sheen) --- *sheen is inspired by [charmbracelet/log](https://github.com/charmbracelet/log). Thanks to them for showing what good logging DX looks like.* ]]> http://localhost:3000/posts/2026-01-18-why-im-building-rapina http://localhost:3000/posts/2026-01-18-why-im-building-rapina Sun, 18 Jan 2026 00:00:00 GMT ) -> Result> { let id = id.into_inner(); if id == 0 { return Err(Error::not_found("user not found")); } Ok(Json(User { id, name: "Antonio".to_string(), email: "antonio@example.com".to_string(), })) } #[post("/users")] async fn create_user(body: Json) -> Json { let input = body.into_inner(); Json(User { id: 1, name: input.name, email: input.email, }) } #[tokio::main] async fn main() -> std::io::Result<()> { let router = Router::new() .get("/users/:id", get_user) .post("/users", create_user); Rapina::new() .router(router) .listen("127.0.0.1:3000") .await } ``` Clean. Typed. Predictable. ## Standardized Errors with Trace IDs Every error returns a consistent envelope: ```json { "error": { "code": "NOT_FOUND", "message": "user not found" }, "trace_id": "550e8400-e29b-41d4-a716-446655440000" } ``` No more guessing what format an error will be in. No more hunting through logs without a trace ID. ## Dependency Injection That Makes Sense ```rust #[derive(Clone)] struct AppConfig { app_name: String, } #[get("/")] async fn hello(config: State) -> String { format!("Hello from {}!", config.into_inner().app_name) } #[tokio::main] async fn main() -> std::io::Result<()> { let config = AppConfig { app_name: "My API".to_string(), }; Rapina::new() .state(config) .router(router) .listen("127.0.0.1:3000") .await } ``` ## Per-Request Dependencies Need auth? Create a `CurrentUser` extractor: ```rust struct CurrentUser { user_id: u64, } impl FromRequestParts for CurrentUser { async fn from_request_parts( parts: &http::request::Parts, _params: &PathParams, _state: &Arc, ) -> Result { let user_id = parts .headers .get("x-user-id") .and_then(|v| v.to_str().ok()) .and_then(|v| v.parse().ok()) .ok_or_else(|| Error::unauthorized("missing or invalid token"))?; Ok(CurrentUser { user_id }) } } #[get("/me")] async fn get_me(user: CurrentUser) -> Json { Json(User { id: user.user_id, name: "Current User".to_string(), email: "me@example.com".to_string(), }) } ``` No auth header? Automatic 401 with a proper error response. No panic. No surprise. ## The Philosophy Rapina follows three principles: - **Predictability** — Clear conventions, obvious structure. You know what to expect. - **Auditability** — Typed contracts, traceable errors. You can prove it's correct. - **Security** — Guardrails by default. You have to opt-out of safety, not opt-in. ## What's Coming Rapina is still young, but the foundation is solid: - [x] Basic router with path parameters - [x] Typed extractors (`Json`, `Path`, `State`) - [x] Proc macros (`#[get]`, `#[post]`, `#[put]`, `#[delete]`) - [x] Standardized error handling with `trace_id` - [x] Dependency injection (`State`, `FromRequestParts`) - [ ] Query parameters extractor - [ ] Validation (`Validated`) - [ ] Auth (Bearer JWT, `CurrentUser`) - [ ] Middleware system - [ ] Observability (tracing, structured logs) - [ ] Automatic OpenAPI generation - [ ] CLI (`rapina new`, `rapina routes`, `rapina doctor`) - [ ] Contract-based testing - [ ] Breaking change detection ## The Ultimate Test If in 5 years someone can: - Understand the API without talking to anyone - Refactor without fear - Let an AI work on it without creating chaos Then Rapina will have fulfilled its purpose. ## Want to Contribute? Rapina is open source and I'd love your help. Whether you're coming from Python, Ruby, PHP, or any other ecosystem—if you care about building APIs that are maintainable, predictable, and AI-friendly, come join us. **GitHub:** [https://github.com/arferreira/rapina](https://github.com/arferreira/rapina) The codebase is clean, the architecture is documented, and there's plenty of low-hanging fruit for first-time contributors: - Adding new extractors (Query, Header, Cookie) - Improving error messages - Writing documentation - Adding examples - Building the middleware system Let's build something we can actually trust. ]]> http://localhost:3000/posts/2026-01-17-how-ai-will-obliterate-your-career http://localhost:3000/posts/2026-01-17-how-ai-will-obliterate-your-career Sat, 17 Jan 2026 00:00:00 GMT http://localhost:3000/posts/2025-08-15-building-a-token-launch-platform-from-scratch http://localhost:3000/posts/2025-08-15-building-a-token-launch-platform-from-scratch Fri, 15 Aug 2025 00:00:00 GMT http://localhost:3000/posts/2024-01-15-the-engineers-who-leave-disasters-behind http://localhost:3000/posts/2024-01-15-the-engineers-who-leave-disasters-behind Mon, 15 Jan 2024 00:00:00 GMT http://localhost:3000/posts/2022-11-15-rewriting-a-carbon-footprint-platform-to-handle-6-million-calculations http://localhost:3000/posts/2022-11-15-rewriting-a-carbon-footprint-platform-to-handle-6-million-calculations Tue, 15 Nov 2022 00:00:00 GMT http://localhost:3000/posts/2022-10-15-what-is-equity-and-why-you-should-care-as-a-tech-lead http://localhost:3000/posts/2022-10-15-what-is-equity-and-why-you-should-care-as-a-tech-lead Sat, 15 Oct 2022 00:00:00 GMT http://localhost:3000/posts/2022-01-15-why-you-dont-need-microservices http://localhost:3000/posts/2022-01-15-why-you-dont-need-microservices Sat, 15 Jan 2022 00:00:00 GMT http://localhost:3000/posts/2020-02-15-como-fui-reprovado-por-ingles-e-resolvi-em-6-meses http://localhost:3000/posts/2020-02-15-como-fui-reprovado-por-ingles-e-resolvi-em-6-meses Sat, 15 Feb 2020 00:00:00 GMT http://localhost:3000/posts/2018-02-15-cryptocurrencies-after-the-crash http://localhost:3000/posts/2018-02-15-cryptocurrencies-after-the-crash Thu, 15 Feb 2018 00:00:00 GMT **Correlation is not causation.** Markets are driven by human behavior — fear, greed, hope, regret — wrapped in numbers. You can analyze tendencies, but you cannot predict outcomes with precision. Anyone claiming certainty is either selling something or lying to themselves. --- ## Risk, Properly Understood The real mistake people made wasn't buying Bitcoin. It was misunderstanding **risk**. Risk isn't volatility. Risk is *position size*. If losing an investment would destroy your life, it was never an investment — it was a gamble. If losing it would hurt, but not break you, then you were engaging in **asymmetric risk**. That asymmetry is what made crypto interesting in the first place: - Limited downside (defined by position sizing) - Massive upside (if adoption continues over years, not weeks) That equation hasn't changed just because prices fell. --- ## "But What If It Never Comes Back?" This question surfaces after every crash in history. And it's always the wrong frame. The better question is: **Did something fundamental break?** As of February 2018: - The network still works - Transactions still settle - Developers are still building - Institutions are still experimenting - Governments are still paying attention That doesn't look like a dead system. It looks like one digesting excess. --- ## The Market Is Less Fun — and That's a Feature Speculative manias are exciting. They're also terrible environments for thinking. After a crash: - Noise disappears - Weak ideas fade - Signal improves - Time horizons lengthen What remains isn't hype — it's conviction. And conviction doesn't shout. --- ## Final Thought So — was 2017 a bubble? Probably. But bubbles are not the opposite of progress. They are the cost of discovering new territory. The dot-com bubble didn't kill the internet. It taught it how to grow up. Cryptocurrencies may be going through the same process. And history suggests that what survives this phase won't look impressive today — but it will be impossible to ignore later. ]]>