DEV Community: Andrei Merlescu

Go + Gin Rust: HTTP Middleware & Web Servers

Andrei Merlescu — Thu, 04 Jun 2026 01:16:40 +0000

I've been programming in Go since 2019 professionally for companies like Oracle, WBGames and SurgePays. Some organizations that I've worked with have legacy code systems that are built using C++ and while I know C++, I do not like C++. Thus, when having conversations with engineering leadership, in too many cases I have felt like there wasn't enough education around Go and how it can be a reliable replacement for any code base built in C++, but if you're biased against go, then Rust is another modern alternative to consider.

Therefore, in this piece, I want to get into a comparison between Go and Rust that explains how Gin Middleware is implemented in Rust, following common concepts expressed in Go using the gin package. For Go, I build the room package which is a FIFO stack waiting room piece of middleware that can be injected into any gin implemented web server in Go. I have not yet ported room over to Rust yet because I haven't studied the internal differences enough yet. This piece will help you study that along with me.

The idea of middleware is to step in between a Start action and Conclusion delivery and either 1) manipulate, 2) modify or 3) gate between the Start action and Conclusion delivery itself.

# START ACTION ↴
Request TCP `:80` ↴
&rarr; Go runtime ↴
&rarr; Gin ↴
&rarr; Gin Middleware ↴ # We'll focus here!
&rarr; Handler Func ↴
&rarr; Response TCP `:80` ↴
# CONCLUSION DELIVERY

Ultimately, this is where room sits in the request stack between each of your route handlers for /home and /about and /contact endpoints. In order to get to the point where a FIFO room can be made for middleware rate limiting with a waiting room itself, a FIFO stack must be manually created in Rust in order to send requests into a multi-threaded environment and get pulled off the FIFO stack per thread. In Go, this is handled automatically, so using the go performLongTask(ctx) is kosher since the runtime scheduler will get this task on a CPU thread for you automatically, but in Rust, if you try to do it from the main thread, then its a single-threaded application, and that will only introduce performance problems down the road. If you need a lot of help managing your threads and what you're doing on each thread, then Go is a better solution for you. If you're ready for low level control to the actual internals of the FIFO handler itself on each thread handling your work, then this tutorial is for you. It's a long one!

When you finish this tutorial, I'll have brought you through 6 distinct cases that you'll encounter in your pursuit of implementing web routing middleware in Rust having come from a background in Go.

Mental Model Shift
Project Setup
Hello World: Server Bootstrapping
Routing
Middleware: The Core Concept
The FIFO Channel Scheduler
Request Lifecycle & Extractors
Error Handling
Full Working Example
Gotchas & Common Problems
Cheat Sheet

There are a lot of tutorials and documents on the internet focusing on C++ → Rust, but few that take you from Go → Rust. I have seen plenty that will take you from C++ → Go, but not Go → Rust - hence why this article was born.

If you find value in it, please comment below what you took, how it helped you, and if there is anything that you want to leave for the next developer to pick up, post it down in the comments if I missed anything. Thanks for reading and enjoy!

1. Mental Model Shift {#mental-model-shift}

Before you write a single line of Rust, it is worth pausing to understand why the two ecosystems look so different on the surface even though they are solving identical problems. Go and Gin were designed around simplicity and developer velocity. The framework makes strong choices for you: a mutable context object flows through every handler, middleware is a slice of functions called in order, and errors are handled imperatively with early returns. This model is easy to teach, easy to read, and maps naturally to how most engineers think about HTTP request processing as a linear pipeline.

Rust and Axum take a different philosophical stance. Axum is built on top of Tower, which is a general-purpose abstraction for networked services. Rather than giving you a mutable context object and a magic Next() function, it gives you composable types. Middleware is not a function in a list — it is a value that wraps another value. A handler is not a special interface — it is any function whose arguments and return type satisfy certain traits. The result is a system where the compiler can verify the correctness of your middleware stack at build time, not at runtime.

This distinction matters enormously when you are debugging. In Gin, a misconfigured middleware chain fails at request time, often with a nil pointer panic or a silent wrong response. In Axum, a misconfigured middleware stack usually fails at compile time with a trait bound error. The error messages are famously cryptic at first, but once you understand the underlying model, they become precise and actionable.

Internalise this comparison table before continuing. Every section of this guide is an expansion of one row in it.

Concept	Go + Gin	Rust + Axum
Handler signature	`func(c *gin.Context)`	`async fn(/* extractors */) -> impl IntoResponse`
Middleware	`gin.HandlerFunc` in a chain	`tower::Layer` wrapping a `Service`
Router	`gin.Engine` (mutable, method calls)	`axum::Router` (immutable builder, returns new value)
Concurrency	goroutines + `net/http` thread pool	`tokio` async tasks
Work queue	`chan` + `select`	`tokio::sync::mpsc` + `select!` macro
Context passing	`*gin.Context` via `Set`/`Get`	typed extractors + `axum::Extension`
Error type	`error` interface, returned or aborted	`impl IntoResponse` or custom error enum

The single most important conceptual shift is this: in Gin, middleware is imperative — you call c.Next() and execution literally jumps forward in a slice of function pointers, then returns. In Axum, middleware is declarative and compositional — you wrap a Service in a Layer, and the runtime calls the outer layer first, which internally calls the inner service as a future. There is no c.Next(). The equivalent is next.run(req).await, which is not magic — it is simply calling an async function that happens to be the rest of your handler stack.

2. Project Setup {#project-setup}

Go + Gin Setup

Setting up a Gin project is straightforward because Go modules and the go get command handle everything in a few commands. Gin itself is a single dependency with no required configuration.

mkdir go-server && cd go-server
go mod init example.com/server
go get github.com/gin-gonic/gin

Rust + Axum Setup

Rust setup requires more deliberate dependency management. The most important thing to understand is that Axum, Tower, Hyper, and tower-http form a tightly coupled version family. Axum 0.7 was a major breaking change from Axum 0.6 — it migrated from Hyper 0.14 to Hyper 1.0. If you mix versions from different generations, you will get extremely confusing trait bound errors that do not mention the real cause. Always pin your versions explicitly and check the Axum changelog before upgrading anything in this dependency group.

The features flags in Cargo.toml are also important. Tokio's full feature enables the entire runtime, including timers, I/O, signal handling, and the multi-threaded scheduler. For production you may want to be more selective, but for learning, full is the right starting point. The tower-http crate provides production-quality middleware implementations — tracing, CORS, timeouts, compression, request ID injection — that would take significant effort to write yourself.

cargo new rust-server && cd rust-server

Your Cargo.toml should look exactly like this. Do not use * for versions in this dependency group.

   [package]
   name = "rust-server"
   version = "0.1.0"
   edition = "2021"

   [dependencies]
   axum = "0.7"
   tokio = { version = "1", features = ["full"] }
   tower = { version = "0.4", features = ["full"] }
   tower-http = { version = "0.5", features = ["trace", "cors", "timeout", "request-id"] }
   hyper = { version = "1", features = ["full"] }
   tracing = "0.1"
   tracing-subscriber = { version = "0.3", features = ["env-filter"] }
   serde = { version = "1", features = ["derive"] }
   serde_json = "1"
   uuid = { version = "1", features = ["v4"] }
   thiserror = "1"
   http = "1"

⚠️ Gotcha #1 — Version coupling is strict in this ecosystem. tower-http version must align with the Hyper version that Axum targets. Axum 0.7 uses Hyper 1.x and tower-http 0.5.x. If you pull in a crate that depends on Hyper 0.14 and try to use it alongside Axum 0.7, the compiler will tell you that trait implementations conflict or are missing — not that your Hyper versions are incompatible. Before adding any HTTP-adjacent crate to an Axum 0.7 project, check whether it has a version that supports Hyper 1.x.

3. Hello World: Server Bootstrapping {#hello-world}

Go + Gin: What Default() Actually Gives You

When most Go developers start a Gin server, they reach for gin.Default() without thinking much about it. It is worth understanding precisely what that function does, because the Rust equivalent requires you to set each piece up explicitly. gin.Default() creates an Engine, which implements Go's standard http.Handler interface, and it pre-registers two middleware functions: Logger and Recovery. Logger writes request details to stdout after every response. Recovery catches any panics that occur during handler execution and converts them to 500 responses, preventing your server from crashing. Both are registered globally, meaning they apply to every route.

The gin.Engine is a mutable struct. You call methods on it to add routes and middleware, and those mutations happen in place. When you call r.Run(), Gin simply delegates to net/http.ListenAndServe, passing itself as the handler. Go's net/http package handles all connection lifecycle management, using goroutines per connection from a managed pool.

   // main.go
   package main

   import (
       "log"
       "net/http"
       "github.com/gin-gonic/gin"
   )

   func main() {
       // gin.Default() attaches Logger and Recovery middleware automatically.
       // Use gin.New() if you want no default middleware at all.
       r := gin.Default()

       r.GET("/ping", func(c *gin.Context) {
           c.JSON(http.StatusOK, gin.H{"message": "pong"})
       })

       // Blocks forever. Listens on :8080.
       log.Fatal(r.Run(":8080"))
   }

Rust + Axum: The Same Server, Explicitly Assembled

In Axum, you build the same result by assembling the pieces that gin.Default() would have given you for free. The tracing subscriber replaces Gin's Logger. Axum does not have a built-in panic recovery middleware, but Tower's ServiceBuilder and tower-http's TraceLayer cover the observability side, and you can add catch-unwind behaviour if needed. Most Rust async code avoids panics entirely by using Result types, which is the idiomatic approach.

The Router in Axum is an immutable builder. Every call to .route(), .layer(), or .merge() returns a new Router value. This is different from Gin's mutable engine and has an important consequence: you compose your router in a single expression tree, and then hand the fully-built value to axum::serve. This makes the router's shape visible at a glance and prevents accidental mutation after the fact.

The #[tokio::main] macro transforms your main function into one that starts the Tokio async runtime and runs the annotated async block on it. This is the entry point for all async code in your binary. Everything downstream of main runs inside the runtime's executor.

   // src/main.rs
   use axum::{routing::get, Router};
   use std::net::SocketAddr;
   use tokio::net::TcpListener;
   use tracing::info;
   use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

   #[tokio::main]
   async fn main() {
       // This replaces gin's built-in Logger middleware.
       // RUST_LOG=info cargo run controls what gets printed.
       tracing_subscriber::registry()
           .with(tracing_subscriber::EnvFilter::new(
               std::env::var("RUST_LOG")
                   .unwrap_or_else(|_| "info".into()),
           ))
           .with(tracing_subscriber::fmt::layer())
           .init();

       // Router is an immutable builder — each method returns a new Router.
       let app = Router::new()
           .route("/ping", get(ping_handler));

       let addr = SocketAddr::from(([0, 0, 0, 0], 8080));

       // TcpListener is the Tokio async equivalent of net.Listen in Go.
       let listener = TcpListener::bind(addr).await.unwrap();

       info!("listening on {}", addr);

       // axum::serve replaced axum::Server::bind in Axum 0.7.
       // This blocks until the server shuts down.
       axum::serve(listener, app).await.unwrap();
   }

   async fn ping_handler() -> axum::Json<serde_json::Value> {
       axum::Json(serde_json::json!({ "message": "pong" }))
   }

Notice that ping_handler takes no arguments and returns a typed JSON value. Axum converts this function into a tower::Service automatically through its Handler trait implementation. The handler does not need to know anything about the HTTP layer — it just receives whatever it declares it needs (via extractors) and returns something that can be turned into a response (via IntoResponse). This separation of concerns is more complete than in Gin, where every handler always receives the full *gin.Context even if it only uses one field.

⚠️ Gotcha #2 — axum::Server was removed in Axum 0.7. A large number of tutorials, blog posts, and Stack Overflow answers target Axum 0.6 and use the axum::Server::bind(&addr).serve(app.into_make_service()) pattern. This code does not compile against Axum 0.7. The correct Axum 0.7 API is TcpListener::bind(addr).await followed by axum::serve(listener, app).await. If your code does not compile and the error mentions axum::Server, you are reading outdated documentation.

4. Routing {#routing}

Go + Gin: Groups, Parameters, and the Mutable Chain

Gin's routing API is designed to read like a configuration file. You call methods on the engine or on a RouterGroup to register routes, and those registrations happen imperatively in order. Route groups share a URL prefix and optionally share middleware. The r.Group() call returns a *RouterGroup, and you call the same HTTP-verb methods on it. Middleware registered with group.Use() only applies to routes registered on that group and its children.

Query parameters are not part of the route definition in Gin — they are pulled from the context at handler time using c.Query() or c.DefaultQuery(). Path parameters are declared with a colon prefix in the route string and retrieved with c.Param(). Both APIs use strings with no compile-time type checking, which means a typo in the parameter name is a runtime bug, not a compile error.

   // main.go
   package main

   import (
       "net/http"
       "github.com/gin-gonic/gin"
   )

   func main() {
       r := gin.Default()

       // Simple routes with HTTP verb methods
       r.GET("/users", listUsers)
       r.POST("/users", createUser)

       // Path parameters use colon syntax in the route string
       r.GET("/users/:id", getUser)

       // Query parameters are handled inside the handler, not in the route
       // GET /search?q=foo&page=2
       r.GET("/search", searchHandler)

       // Route groups share a URL prefix and optionally share middleware.
       // The braces are a Go scoping convention, not required syntax.
       api := r.Group("/api/v1")
       {
           api.GET("/products", listProducts)
           api.GET("/products/:id", getProduct)

           // Nested group — admin middleware only applies to these routes
           admin := api.Group("/admin")
           admin.Use(adminAuthMiddleware())
           {
               admin.DELETE("/products/:id", deleteProduct)
           }
       }

       r.Run(":8080")
   }

   func listUsers(c *gin.Context) {
       c.JSON(http.StatusOK, gin.H{"users": []string{}})
   }

   func getUser(c *gin.Context) {
       // c.Param() retrieves the path parameter by name — string only
       id := c.Param("id")
       c.JSON(http.StatusOK, gin.H{"id": id})
   }

   func searchHandler(c *gin.Context) {
       q := c.Query("q")                    // returns "" if missing
       page := c.DefaultQuery("page", "1")  // returns "1" if missing
       c.JSON(http.StatusOK, gin.H{"q": q, "page": page})
   }

   func createUser(c *gin.Context)    { c.Status(201) }
   func listProducts(c *gin.Context)  { c.Status(200) }
   func getProduct(c *gin.Context)    { c.Status(200) }
   func deleteProduct(c *gin.Context) { c.Status(204) }

   func adminAuthMiddleware() gin.HandlerFunc {
       return func(c *gin.Context) { c.Next() }
   }

Rust + Axum: Typed Extractors Replace the Context Object

Axum's routing model eliminates the context object entirely. Instead of a single *gin.Context that carries everything, each handler declares exactly what it needs as typed function parameters. These typed parameters are called extractors, and Axum's framework automatically runs the extraction logic and passes the result to your function. If extraction fails — for example, a required query parameter is missing, or the JSON body cannot be deserialized — Axum returns an appropriate error response before your handler is even called.

Route groups are replaced by the Router::nest() method, which mounts a sub-router under a prefix. Middleware is applied to a sub-router using .layer(), which scopes the middleware to only the routes in that sub-router. This is a more explicit and composable model than Gin's group-level Use().

The structural difference to emphasise here is that Router is a value, not a reference. You cannot pass a Router to a function and mutate it — you return a new Router from each function call. This means your routing configuration is naturally expressed as a tree of pure functions returning values, which makes it easy to test, compose, and reason about.

   // src/routes/mod.rs
   use axum::{
       Router,
       routing::{delete, get, post},
       extract::{Path, Query, State},
       Json,
       http::StatusCode,
   };
   use serde::Deserialize;
   use crate::AppState;

   // This function builds and returns the complete router for the application.
   // It is called once at startup and the result is handed to axum::serve.
   // There is no global mutable engine — just a value built from composition.
   pub fn build_router(state: AppState) -> Router {
       // Public routes that require no authentication
       let public_routes = Router::new()
           .route("/users", get(list_users).post(create_user))
           .route("/users/:id", get(get_user))
           .route("/search", get(search_handler));

       // Admin routes — middleware will be applied to this sub-router
       // in the middleware section below. Shown here for structure only.
       let admin_routes = Router::new()
           .route("/products/:id", delete(delete_product));

       // API v1 group — equivalent to r.Group("/api/v1") in Gin.
       // The admin sub-router is nested under /api/v1/admin.
       let api_v1 = Router::new()
           .route("/products", get(list_products))
           .route("/products/:id", get(get_product))
           .nest("/admin", admin_routes);

       // Assemble the top-level router.
       // State is attached at the root and automatically flows to all
       // nested routers and handlers that declare State<AppState>.
       Router::new()
           .merge(public_routes)
           .nest("/api/v1", api_v1)
           .with_state(state)
   }

   // Handlers follow below the router definition.
   // Each handler only takes the extractors it actually needs.

   async fn list_users() -> Json<serde_json::Value> {
       Json(serde_json::json!({ "users": [] }))
   }

   // Path extractor is typed. The compiler knows the parameter is a String.
   // A typo in the extractor variable name produces a compile error, not a
   // runtime bug as it would with c.Param("typo") in Gin.
   async fn get_user(Path(id): Path<String>) -> Json<serde_json::Value> {
       Json(serde_json::json!({ "id": id }))
   }

   async fn create_user() -> StatusCode {
       StatusCode::CREATED
   }

   // Query params are deserialized into a typed struct automatically.
   // serde's default attribute replaces DefaultQuery in Gin.
   // If a required field (non-Option) is missing, Axum returns 422 automatically.
   #[derive(Deserialize)]
   struct SearchParams {
       q: Option<String>,
       #[serde(default = "default_page")]
       page: String,
   }

   fn default_page() -> String {
       "1".to_string()
   }

   async fn search_handler(
       Query(params): Query<SearchParams>,
   ) -> Json<serde_json::Value> {
       Json(serde_json::json!({
           "q": params.q.unwrap_or_default(),
           "page": params.page,
       }))
   }

   async fn list_products() -> StatusCode { StatusCode::OK }
   async fn get_product(Path(_id): Path<String>) -> StatusCode { StatusCode::OK }
   async fn delete_product(Path(_id): Path<String>) -> StatusCode { StatusCode::NO_CONTENT }

⚠️ Gotcha #3 — Extractor ordering in handler function signatures is enforced by the compiler and easy to get wrong. Axum processes extractors in the order they appear. Because reading the request body consumes the byte stream, the body extractor — Json<T>, Bytes, String, or Form<T> — must always be the last parameter. Any extractor that appears after the body extractor will fail to compile with a confusing error message about missing trait implementations. The safe ordering is: State → Path → Query → HeaderMap → Extension → body extractor last.

5. Middleware: The Core Concept {#middleware}

This is the most critical section of this guide. If you read only one section carefully, let it be this one. The difference between how Gin and Axum implement middleware is not just syntactic — it reflects fundamentally different architectural philosophies, and getting the Axum model wrong produces bugs that are difficult to trace.

How Gin Middleware Works: The Handler Chain

Gin stores middleware as a flat slice of HandlerFunc values on the engine and on each route group. When a request arrives and matches a route, Gin builds a merged slice of all applicable middleware functions followed by the route's own handler function. It then executes this slice sequentially, advancing an index pointer. Calling c.Next() increments that pointer and executes the next function in the slice. When the last function returns, control unwinds back through every c.Next() call site, executing any code that appears after c.Next() in each middleware in reverse registration order.

Calling c.Abort() or c.AbortWithStatusJSON() sets a flag that prevents the index from advancing further. Any middleware that checks c.IsAborted() or any code after a c.Next() call will still execute in the aborting middleware, but no further functions in the chain will be invoked.

This model is intuitive but has a subtle implication: every middleware in the chain shares the same mutable *gin.Context. Values are passed between middleware and handlers via untyped string keys in a map (c.Set and c.Get). A typo in a key name is a runtime bug. A type assertion failure from c.Get is a runtime panic. These are not problems you can catch at compile time.

   // Gin middleware is a HandlerFunc. c.Next() advances the handler chain.
   // Handlers are stored as []HandlerFunc and executed in order (FIFO).
   // Code before c.Next() runs on the way IN.
   // Code after c.Next() runs on the way OUT, after the response is written.

   func TimingMiddleware() gin.HandlerFunc {
       return func(c *gin.Context) {
           start := time.Now()

           // Save anything you need before the downstream handlers run
           method := c.Request.Method
           uri := c.Request.RequestURI

           c.Next() // Execution jumps forward. This line blocks until
                    // all remaining handlers complete and return.

           // This code runs after the response has been written
           duration := time.Since(start)
           log.Printf("[%s] %s took %v", method, uri, duration)
       }
   }

   func AuthMiddleware() gin.HandlerFunc {
       return func(c *gin.Context) {
           token := c.GetHeader("Authorization")
           if token == "" {
               // AbortWithStatusJSON writes the response AND prevents
               // c.Next() from advancing. The return prevents any code
               // after this block from running in this middleware function.
               c.AbortWithStatusJSON(401, gin.H{"error": "unauthorized"})
               return
           }

           // Passing data to downstream handlers via untyped map.
           // The key is a string — a typo here is a runtime bug.
           c.Set("user_id", "user-123")
           c.Next()
       }
   }

   func main() {
       r := gin.New() // gin.New() gives you no default middleware

       // Middleware is registered globally in FIFO order.
       // TimingMiddleware runs first on the way in, last on the way out.
       r.Use(TimingMiddleware())
       r.Use(AuthMiddleware())

       r.GET("/protected", func(c *gin.Context) {
           // Type assertion from interface{} — can panic if middleware
           // didn't set this key or set a different type.
           userID, _ := c.Get("user_id")
           c.JSON(200, gin.H{"user": userID})
       })
   }

Gin's execution model visualised:

   Request arrives
       │
       ▼
   [TimingMiddleware — code before c.Next()]  ← records start time
       │
       ▼
   [AuthMiddleware — code before c.Next()]    ← validates token, sets user_id
       │
       ▼
   [Route Handler — c.JSON(200, ...)]         ← reads user_id, writes response
       │
       ▼
   [AuthMiddleware — code after c.Next()]     ← nothing here in our example
       │
       ▼
   [TimingMiddleware — code after c.Next()]   ← logs duration
       │
       ▼
   Response sent to client

How Tower/Axum Middleware Works: Composed Services

Tower middleware is built on two fundamental traits that you need to understand even if you never implement them manually. Service<Request> represents anything that can process a request and produce a response asynchronously. Layer<S> represents a factory that wraps a Service in another Service — it transforms an inner service into an outer service that adds some behaviour.

When you call .layer(MyLayer) on an Axum Router, you are telling Axum: take the current service, and wrap it with MyLayer. The outer service produced by the layer receives requests first, does its pre-processing work, then calls the inner service. When the inner service returns a response, the outer service can do post-processing before returning the response upstream. This is mechanically identical to Gin's before/after c.Next() pattern, but expressed as function composition rather than an index pointer in a slice.

   // The two traits you must understand to reason about Axum middleware:

   pub trait Service<Request> {
       type Response;
       type Error;
       type Future: Future<Output = Result<Self::Response, Self::Error>>;

       // Called before each request to check if the service can accept work.
       // This is Tower's backpressure mechanism — no equivalent in Gin.
       fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

       // Called with the request. Returns a Future that resolves to the response.
       // This is where your middleware logic lives.
       fn call(&mut self, req: Request) -> Self::Future;
   }

   pub trait Layer<S> {
       type Service;

       // Wraps the inner Service S and returns a new Service.
       // This is called once at startup, not per-request.
       fn layer(&self, inner: S) -> Self::Service;
   }

   // A Layer wraps a Service to produce a new Service.
   // Layers compose: the outermost layer runs first on request in,
   // and last on response out — identical to Gin's before/after Next() pattern.
   // The key difference is that this composition happens at compile time,
   // not at request time, and the compiler verifies the types are compatible.

Writing a Timing Middleware Using `from_fn`

The axum::middleware::from_fn function is the idiomatic way to write middleware for most production use cases. It takes an async function with a specific signature and wraps it in a Tower Layer so you can use it with .layer(). This avoids the significant boilerplate of implementing Service and Layer manually.

The next: Next parameter is the functional equivalent of c.Next() in Gin. Calling next.run(req).await invokes the rest of the middleware stack and the route handler, then returns their combined response. Everything before next.run() is pre-processing (equivalent to code before c.Next() in Gin). Everything after is post-processing (equivalent to code after c.Next()).

   // src/middleware/timing.rs
   //
   // axum::middleware::from_fn wraps this function as a Tower middleware Layer.
   // The function signature must match exactly: (Request, Next) -> Response.
   // The async keyword is required because middleware is always async in Axum —
   // the runtime needs to be able to yield control while waiting for downstream
   // handlers to complete.
   use axum::{
       body::Body,
       extract::Request,
       middleware::Next,
       response::Response,
   };
   use std::time::Instant;
   use tracing::info;

   pub async fn timing_middleware(
       req: Request,
       next: Next,
   ) -> Response {
       // Everything here runs BEFORE the downstream handlers.
       // Equivalent to code before c.Next() in Gin.
       // We extract what we need from the request before moving it into next.run(),
       // because the Request value is consumed when passed to next.run().
       let start = Instant::now();
       let method = req.method().clone();
       let uri = req.uri().clone();

       // This is the equivalent of c.Next() in Gin.
       // It awaits the completion of all remaining middleware and handlers.
       // The request is moved in and the response is returned.
       let response = next.run(req).await;

       // Everything here runs AFTER the downstream handlers complete.
       // Equivalent to code after c.Next() in Gin.
       // The response has been produced but not yet sent to the client.
       // You can inspect or modify it here.
       let duration = start.elapsed();
       info!(
           method = %method,
           uri = %uri,
           status = response.status().as_u16(),
           duration_ms = duration.as_millis(),
           "request completed"
       );

       response
   }

Writing an Auth Middleware That Can Short-Circuit

The early-return pattern replaces c.AbortWithStatusJSON(). Because middleware is just an async function that returns a Response, you can return any response at any point. Simply returning before calling next.run(req) is equivalent to c.Abort() — the downstream middleware and handler are never called.

The type-safe value passing mechanism is request extensions. Rather than storing values in a map[string]interface{} as Gin does with c.Set(), Axum uses a typed map in the request's extension storage. Each type can have exactly one entry. You insert a value with req.extensions_mut().insert(MyValue { ... }), and you retrieve it in a handler with the Extension<MyValue> extractor. The compiler knows the type — no interface, no string key, no type assertion.

   // src/middleware/auth.rs
   //
   // This middleware checks for an Authorization header and either
   // short-circuits with a 401 response or injects the authenticated user
   // into the request extensions for downstream handlers to retrieve.
   // It is the direct equivalent of Gin's AbortWithStatusJSON + c.Set() pattern.
   use axum::{
       extract::Request,
       middleware::Next,
       response::{IntoResponse, Response},
       Json,
       http::StatusCode,
   };
   use serde_json::json;

   // This is the typed value we pass from middleware to handler.
   // In Gin you would store this as c.Set("user", map[string]interface{}{...}).
   // In Axum it is a real struct with a real type, verified by the compiler.
   // Handlers that declare Extension<AuthenticatedUser> will receive exactly this.
   #[derive(Clone)]
   pub struct AuthenticatedUser {
       pub id: String,
       pub token: String,
   }

   pub async fn auth_middleware(
       mut req: Request,
       next: Next,
   ) -> Response {
       let token = req
           .headers()
           .get("Authorization")
           .and_then(|v| v.to_str().ok())
           .map(|s| s.to_string());

       match token {
           // No token or empty string — return early, just like c.AbortWithStatusJSON.
           // next.run() is never called. Downstream handlers are never invoked.
           None | Some(ref t) if t.is_empty() => {
               return (
                   StatusCode::UNAUTHORIZED,
                   Json(json!({ "error": "unauthorized" })),
               )
                   .into_response();
           }
           Some(token) => {
               // Insert the typed user value into the request's extension map.
               // This is the equivalent of c.Set("user_id", "user-123").
               // The type AuthenticatedUser is the key — only one can exist per request.
               req.extensions_mut().insert(AuthenticatedUser {
                   id: "user-123".to_string(),
                   token,
               });
           }
       }

       // Call the remaining middleware and handler.
       // Equivalent to c.Next() after a successful auth check.
       next.run(req).await
   }

Extracting Middleware-Injected Data in a Handler

Retrieving values that middleware injected is done through the Extension extractor. The type parameter tells Axum which extension to retrieve. If the extension is not present — because the middleware that sets it was not applied to this route, or because it returned early — Axum returns a 500 error. To handle the optional case gracefully, use Option<Extension<T>>.

   // src/handlers/protected.rs
   //
   // The Extension extractor retrieves the typed value that auth_middleware
   // inserted into the request extensions. If AuthenticatedUser is not in
   // the extensions, Axum returns 500 automatically. This prevents handlers
   // from running in a partially-authenticated state, which is a class of bug
   // that is easy to introduce with Gin's untyped c.Get() pattern.
   use axum::{Extension, Json};
   use crate::middleware::auth::AuthenticatedUser;

   pub async fn protected_handler(
       // This extractor fails with 500 if auth middleware did not inject the value.
       // Use Option<Extension<AuthenticatedUser>> if the field is optional.
       Extension(user): Extension<AuthenticatedUser>,
   ) -> Json<serde_json::Value> {
       axum::Json(serde_json::json!({ "user": user.id }))
   }

Applying Middleware: Global vs Route-Scoped

One of Axum's most powerful features is precise middleware scoping. In Gin, scoping middleware to a group of routes requires creating a RouterGroup and calling group.Use(). In Axum, you apply middleware to a sub-router with .layer(), and it affects only the routes in that router. The top-level .layer() applies globally. This allows you to have a public health check route that bypasses authentication while all other routes require it, without any special-casing in the auth middleware itself.

   // src/main.rs (routing and middleware wiring section)
   //
   // This shows how to apply middleware at different scopes.
   // Global middleware wraps the entire app.
   // Scoped middleware wraps only a sub-router.
   use axum::middleware;
   use tower_http::trace::TraceLayer;
   use crate::middleware::{auth::auth_middleware, timing::timing_middleware};

   fn build_app(state: AppState) -> Router {
       // These routes require authentication.
       // The auth middleware is applied only to this sub-router.
       let protected = Router::new()
           .route("/protected", get(protected_handler))
           .layer(middleware::from_fn(auth_middleware));

       Router::new()
           // This public route is NOT wrapped by auth middleware.
           .route("/ping", get(ping_handler))
           .merge(protected)
           // tower_http's TraceLayer produces structured HTTP request/response logs.
           // This is the closest equivalent to gin's built-in Logger middleware.
           .layer(TraceLayer::new_for_http())
           // Our custom timing middleware wraps everything including TraceLayer.
           .layer(middleware::from_fn(timing_middleware))
           .with_state(state)
   }

⚠️ Gotcha #4 — Layer ordering in Axum is the opposite of what Go developers expect, and this is the most common source of middleware ordering bugs. In Gin, r.Use(A); r.Use(B) means A runs first on every request. In Axum, .layer(A).layer(B) means B runs first. Each new .layer() call wraps the existing service on the outside. The last .layer() call produces the outermost service, and the outermost service handles the request first. Think of it as wrapping a present: the last paper you apply is the outermost layer and the first thing the recipient encounters.

   // This is the execution order for:
   // Router::new()
   //     .layer(LoggingLayer)   ← added first, runs SECOND on request in
   //     .layer(AuthLayer)      ← added last, runs FIRST on request in
   //
   // Request path:  AuthLayer → LoggingLayer → Handler
   // Response path: Handler   → LoggingLayer → AuthLayer
   //
   // To match Gin's r.Use(Auth); r.Use(Logging) ordering:
   // Router::new()
   //     .layer(LoggingLayer)   ← Gin's second Use() → Axum's first layer()
   //     .layer(AuthLayer)      ← Gin's first Use()  → Axum's second layer()

6. The FIFO Channel Scheduler {#fifo-channel-scheduler}

Many production services need to offload work from the HTTP request path to a background worker. Common examples include sending emails, writing audit logs, calling slow third-party APIs, or processing uploaded files. In Go, this pattern is typically implemented with a buffered channel and a goroutine running a select loop. The channel provides FIFO ordering as a language-level guarantee: messages are delivered to the receiver in the order they were sent, and select allows the loop to simultaneously wait for work and for a shutdown signal.

Rust provides the same pattern through Tokio's mpsc channel and the select! macro. The mechanics are nearly identical in intent but differ in important ways that reflect Rust's ownership model and async execution model. Understanding these differences upfront will save you significant debugging time.

The key semantic difference between Go's select and Tokio's select! is fairness. Go's select with multiple ready cases picks one uniformly at random. Tokio's select! also polls branches in a pseudo-random order by default, but it provides a biased; directive that makes it poll branches in declaration order. This is useful when you want shutdown signals to take priority over queued work, which is the correct behaviour for a graceful shutdown.

Go Pattern: Channel + Select Loop

In Go, the scheduler is typically a struct that owns both the work channel and a stop signal. The Submit method is called from HTTP handlers — it is synchronous from the caller's perspective (it blocks if the channel buffer is full). The Run method is started in a goroutine at startup and loops forever until the stop signal fires.

   // worker/scheduler.go
   package worker

   import (
       "context"
       "log"
   )

   type Job struct {
       ID      string
       Payload any
   }

   type Scheduler struct {
       queue chan Job
       stop  chan struct{}
   }

   func NewScheduler(bufferSize int) *Scheduler {
       return &Scheduler{
           queue: make(chan Job, bufferSize),
           stop:  make(chan struct{}),
       }
   }

   // Submit enqueues a job. Called from HTTP handlers.
   // If the buffer is full, this call blocks until space is available.
   // For non-blocking submission, use a select with a default case.
   func (s *Scheduler) Submit(job Job) {
       s.queue <- job
   }

   // Run is the FIFO worker loop. Start this in a goroutine.
   // Jobs are processed in arrival order because Go channels are FIFO.
   // The select waits for whichever case is ready: a new job or a stop signal.
   func (s *Scheduler) Run(ctx context.Context) {
       for {
           select {
           case job := <-s.queue:
               // Processing happens synchronously in the loop,
               // which guarantees strict FIFO order for this single worker.
               processJob(job)
           case <-s.stop:
               log.Println("scheduler shutting down")
               return
           case <-ctx.Done():
               log.Println("context cancelled, scheduler stopping")
               return
           }
       }
   }

   func (s *Scheduler) Stop() {
       close(s.stop)
   }

   func processJob(job Job) {
       log.Printf("processing job %s", job.ID)
   }

Rust Pattern: `tokio::sync::mpsc` + `select!`

The Tokio version of this pattern replaces goroutines with async tasks and channels with Tokio's async-aware channel types. The most important distinction is that Tokio's mpsc::Sender::send() is an async fn — it must be awaited. This is because in an async runtime, "waiting for buffer space" is not a thread block, it is a yield point that allows other tasks to run. The Rust equivalent of Go's blocking channel send is sender.send(job).await.

The worker loop is spawned as a Tokio task using tokio::spawn. Like go func(), this creates a concurrent unit of execution. Unlike a goroutine, a Tokio task is not a thread — it is a future that the runtime polls on its thread pool. Multiple tasks can run on the same OS thread. This means that blocking inside a task (using std::thread::sleep, std::sync::Mutex::lock under contention, or synchronous file I/O) can stall the entire runtime thread and degrade the performance of every other task on that thread.

   // src/worker/scheduler.rs
   //
   // This module implements the FIFO work queue using Tokio's mpsc channel.
   // The Sender half is cloned and distributed to HTTP handlers.
   // The Receiver half is owned by the background worker task.
   // FIFO is guaranteed: mpsc channels deliver messages in send order
   // to a single receiver, just like a Go buffered channel.
   use tokio::sync::{mpsc, oneshot};
   use tokio::select;
   use tracing::{info, warn};

   #[derive(Debug)]
   pub struct Job {
       pub id: String,
       pub payload: serde_json::Value,
       // The oneshot channel here implements the Go "done channel" pattern.
       // If the HTTP handler wants to wait for a result, it sends a Sender here.
       // The worker sends the result back through it when the job is complete.
       // If the handler does not need a result (fire-and-forget), this is None.
       pub reply: Option<oneshot::Sender<JobResult>>,
   }

   #[derive(Debug)]
   pub struct JobResult {
       pub success: bool,
       pub message: String,
   }

   // Scheduler owns only the Sender. The Receiver is returned separately
   // so it can be passed to the background worker task without sharing ownership.
   // This pattern prevents the common mistake of trying to receive from multiple
   // places, which the type system enforces: Receiver is not Clone.
   pub struct Scheduler {
       pub sender: mpsc::Sender<Job>,
   }

   impl Scheduler {
       pub fn new(buffer_size: usize) -> (Self, mpsc::Receiver<Job>) {
           let (sender, receiver) = mpsc::channel(buffer_size);
           (Self { sender }, receiver)
       }
   }

   // The worker loop runs as a Tokio task, not an OS thread.
   // It is the direct equivalent of Go's goroutine + for { select {} } pattern.
   // The biased; directive in select! makes shutdown take priority over pending jobs,
   // which is the correct behaviour for graceful shutdown.
   // Without biased;, select! randomly chooses among ready branches, which could
   // process jobs indefinitely even after a shutdown signal is received.
   pub async fn run_scheduler(
       mut receiver: mpsc::Receiver<Job>,
       mut shutdown: tokio::sync::broadcast::Receiver<()>,
   ) {
       info!("scheduler started");

       loop {
           select! {
               // biased; makes select! check branches in declaration order.
               // Shutdown is checked first. If both shutdown and a job are ready,
               // shutdown always wins. This prevents processing new work after
               // a shutdown signal is received.
               biased;

               _ = shutdown.recv() => {
                   info!("scheduler received shutdown signal");
                   break;
               }

               // recv() returns None when all Sender halves have been dropped,
               // which naturally signals that no more work will ever arrive.
               // This is equivalent to the channel being closed in Go.
               job = receiver.recv() => {
                   match job {
                       Some(job) => {
                           process_job(job).await;
                       }
                       None => {
                           warn!("all senders dropped, scheduler exiting");
                           break;
                       }
                   }
               }
           }
       }

       info!("scheduler shut down cleanly");
   }

   // Individual job processing. Because this is async, it can await I/O,
   // database calls, or external API requests without blocking the runtime thread.
   // The FIFO order is preserved because run_scheduler processes one job at a time
   // sequentially within its loop. If you want parallel processing, spawn each
   // process_job call as a separate tokio::spawn task — but that sacrifices strict FIFO.
   async fn process_job(job: Job) {
       info!(job_id = %job.id, "processing job");

       // Simulate async work such as a database write or API call
       tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;

       let result = JobResult {
           success: true,
           message: format!("job {} completed", job.id),
       };

       // Send the result back to the waiting HTTP handler if it is listening.
       // If the handler has already given up and dropped the Receiver,
       // the send fails silently. This is correct — we do not want the worker
       // to panic just because the client disconnected.
       if let Some(reply) = job.reply {
           let _ = reply.send(result);
       }
   }

Wiring the Scheduler into the HTTP Server

The scheduler is created in main before the server starts. The Sender half is stored in AppState and distributed to every handler that needs it. The Receiver half is moved into the background task. The broadcast channel provides the shutdown signal — it can have multiple receivers, which means both the scheduler and any other background tasks can all listen for the same shutdown event.

   // src/main.rs
   //
   // Full server bootstrap with scheduler integration.
   // This shows the complete startup sequence that Go developers should
   // map to their mental model of: init state, start goroutines, start server.
   use tokio::sync::broadcast;
   use crate::worker::scheduler::{run_scheduler, Scheduler};
   use crate::state::AppState;

   #[tokio::main]
   async fn main() {
       tracing_subscriber::registry()
           .with(tracing_subscriber::EnvFilter::new(
               std::env::var("RUST_LOG")
                   .unwrap_or_else(|_| "info".into()),
           ))
           .with(tracing_subscriber::fmt::layer())
           .init();

       // Broadcast channel for clean shutdown signaling.
       // broadcast::Sender can be cloned and distributed to multiple subsystems.
       // This is the equivalent of a shared context.WithCancel in Go.
       let (shutdown_tx, shutdown_rx) = broadcast::channel::<()>(1);

       // Create the FIFO work queue.
       // Sender goes into AppState. Receiver goes to the background task.
       let (scheduler, receiver) = Scheduler::new(100);

       // Spawn the scheduler as a background async task.
       // This is the equivalent of: go sched.Run(ctx)
       tokio::spawn(run_scheduler(receiver, shutdown_rx));

       let state = AppState {
           job_sender: scheduler.sender.clone(),
       };

       let app = crate::routes::build_router(state);
       let addr = std::net::SocketAddr::from(([0, 0, 0, 0], 8080));
       let listener = tokio::net::TcpListener::bind(addr).await.unwrap();

       tracing::info!("listening on {}", addr);

       // with_graceful_shutdown allows the server to finish in-flight requests
       // before shutting down. The future passed here is awaited, and when it
       // resolves, the server stops accepting new connections and waits for
       // existing connections to close. This is the equivalent of Go's
       // http.Server.Shutdown(ctx) with a done channel.
       axum::serve(listener, app)
           .with_graceful_shutdown(async move {
               tokio::signal::ctrl_c().await.unwrap();
               tracing::info!("shutdown signal received");
               // Signal all broadcast receivers — the scheduler and any
               // other tasks listening on a clone of shutdown_rx.
               let _ = shutdown_tx.send(());
           })
           .await
           .unwrap();
   }

Submitting Jobs from an HTTP Handler

There are two submission patterns: fire-and-forget (submit and return 202 immediately) and synchronous (submit and wait for a result using a oneshot channel). The latter is the Rust equivalent of Go's done channel pattern — the HTTP handler holds the receiving end of a oneshot channel, the job carries the sending end, and the worker sends through it when complete.

   // src/handlers/jobs.rs
   //
   // Two submission patterns demonstrating fire-and-forget and synchronous variants.
   // The synchronous variant uses a oneshot channel, which is the Rust equivalent
   // of Go's common pattern: done := make(chan Result, 1); job.done = done; result := <-done
   use axum::{extract::State, Json, http::StatusCode};
   use tokio::sync::oneshot;
   use serde::Deserialize;
   use uuid::Uuid;
   use crate::{
       state::AppState,
       worker::scheduler::{Job, JobResult},
   };

   #[derive(Deserialize)]
   pub struct CreateJobRequest {
       pub payload: serde_json::Value,
   }

   // Fire-and-forget: submit the job to the FIFO queue and return 202 immediately.
   // The client does not wait for the job to complete.
   // If the channel buffer is full, the send fails and we return 503.
   // mpsc::Sender::send().await blocks the current task until buffer space opens.
   // Use try_send() for the non-blocking equivalent of Go's:
   //   select { case ch <- job: default: return ErrQueueFull }
   pub async fn submit_job(
       State(state): State<AppState>,
       Json(body): Json<CreateJobRequest>,
   ) -> StatusCode {
       let job = Job {
           id: Uuid::new_v4().to_string(),
           payload: body.payload,
           reply: None,
       };

       match state.job_sender.send(job).await {
           Ok(_) => StatusCode::ACCEPTED,
           Err(_) => StatusCode::SERVICE_UNAVAILABLE,
       }
   }

   // Synchronous: submit the job and wait for the worker to complete it.
   // Uses a oneshot channel so the HTTP handler can await the job result.
   // This pattern is useful when the client needs confirmation that the work
   // was actually performed, not just that it was queued.
   pub async fn submit_job_sync(
       State(state): State<AppState>,
       Json(body): Json<CreateJobRequest>,
   ) -> Result<Json<serde_json::Value>, StatusCode> {
       // Create a single-use channel for the reply.
       // reply_tx goes into the job. reply_rx stays here to await the result.
       let (reply_tx, reply_rx) = oneshot::channel::<JobResult>();

       let job = Job {
           id: Uuid::new_v4().to_string(),
           payload: body.payload,
           reply: Some(reply_tx),
       };

       state.job_sender
           .send(job)
           .await
           .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;

       // Block this handler task until the worker sends a result.
       // The runtime thread is not blocked — other tasks continue to run.
       // Equivalent to: result := <-done in Go.
       match reply_rx.await {
           Ok(result) => Ok(Json(serde_json::json!({
               "success": result.success,
               "message": result.message,
           }))),
           Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR),
       }
   }

⚠️ Gotcha #5 — You must never block a Tokio async task with synchronous blocking calls. In Go, each goroutine has its own stack and blocking one goroutine is cheap — the runtime creates more. In Tokio, the default multi-threaded scheduler runs tasks on a fixed pool of OS threads (defaulting to one per CPU core). If you call std::thread::sleep, std::sync::Mutex::lock under contention, or any synchronous file/network I/O inside an async task, you block that thread and all other tasks scheduled on it stall. Always use tokio::time::sleep, tokio::sync::Mutex, and tokio::fs/tokio::net inside async contexts. For unavoidably blocking operations like calling a blocking C library, use tokio::task::spawn_blocking to run the work on a dedicated blocking thread pool.

7. Request Lifecycle & Extractors {#extractors}

The God Object vs the Typed Contract

Go developers who come to Axum experience the extractor system as both the most unfamiliar and ultimately the most appreciated design choice. In Gin, every handler receives the same *gin.Context regardless of what it actually needs. You call methods on that object to access path parameters, query strings, headers, the body, and the response writer. The context is a mutable god object — it contains everything and can do everything. This is convenient and familiar, but it comes with costs: handlers cannot self-document their dependencies, and nothing prevents a handler from reading the body twice, writing headers after the body, or skipping response finalization.

In Axum, the function signature is the contract. A handler that needs a path parameter, a query parameter, and a JSON body declares all three as typed function arguments. The framework reads that declaration, runs the extraction logic, and either delivers the extracted values to your function or returns an appropriate error response before your function is even called. A handler that only needs the path parameter does not receive anything else — it cannot accidentally read a header that should have been processed in middleware, and it cannot call any method that would be inappropriate at that point in the request lifecycle.

This approach also makes handlers significantly easier to unit test. Instead of constructing a mock *gin.Context with all its internal state, you can call an Axum handler function directly with typed values and assert on its typed return value.

   // Gin: every handler gets the full context regardless of what it needs.
   // There is no declaration of intent — the reader must inspect the body
   // of the function to understand what it actually uses.
   func handler(c *gin.Context) {
       id := c.Param("id")
       page := c.Query("page")
       auth := c.GetHeader("Authorization")
       var body MyStruct
       c.ShouldBindJSON(&body)
       c.Header("X-Request-ID", "abc")
       c.JSON(200, gin.H{"id": id})
   }

   // Rust + Axum: the function signature declares exactly what this handler uses.
   // You can read the signature and know the complete set of inputs.
   // Adding a new dependency is explicit and visible in code review.
   use axum::{
       extract::{Path, Query, State},
       Json,
       http::{HeaderMap, StatusCode},
       response::IntoResponse,
   };
   use serde::{Deserialize, Serialize};

   #[derive(Deserialize)]
   struct UserQuery {
       page: Option<u32>,
   }

   #[derive(Deserialize)]
   struct CreateBody {
       name: String,
       email: String,
   }

   #[derive(Serialize)]
   struct UserResponse {
       id: String,
       name: String,
   }

   // Every parameter here is verified by the compiler.
   // State<AppState> requires AppState to be registered with .with_state().
   // Path<String> requires a route parameter to be declared in the route string.
   // Query<UserQuery> deserializes the query string into the struct.
   // HeaderMap gives access to all request headers without parsing overhead.
   // Json<CreateBody> reads and deserializes the request body — MUST be last.
   async fn full_example_handler(
       State(state): State<AppState>,
       Path(id): Path<String>,
       Query(params): Query<UserQuery>,
       headers: HeaderMap,
       Json(body): Json<CreateBody>,
   ) -> Result<Json<UserResponse>, StatusCode> {
       let auth = headers
           .get("Authorization")
           .and_then(|v| v.to_str().ok())
           .unwrap_or("");

       tracing::info!(id, page = ?params.page, auth, "handling request");

       Ok(Json(UserResponse {
           id,
           name: body.name,
       }))
   }

   // Returning custom response headers requires returning a tuple.
   // Axum's IntoResponse is implemented for tuples up to a certain arity.
   // (StatusCode, HeaderMap, Json<T>) is the pattern for status + headers + body.
   async fn handler_with_headers() -> impl IntoResponse {
       let mut headers = HeaderMap::new();
       headers.insert(
           "X-Request-ID",
           "abc-123".parse().unwrap(),
       );
       (StatusCode::OK, headers, Json(serde_json::json!({"ok": true})))
   }

Shared State: From Closures to `AppState`

In Go, shared state is often passed to handlers via closures — the handler function is defined inside a method on an app struct and closes over the struct's fields. Alternatively, Gin provides a built-in key-value store on the engine. Both approaches use untyped storage under the hood, and the second approach requires passing state through middleware as interface values.

Axum's approach is more explicit. You define a typed state struct, derive Clone on it, pass it to the router with .with_state(), and retrieve it in handlers with the State<AppState> extractor. The clone happens once per request — Axum clones the state to give each handler its own copy. For types that are expensive to clone, wrap them in Arc<T>, which is a reference-counted pointer that makes cloning cheap (it just increments a counter) while sharing the underlying data.

   // Go: state via closure or via gin engine key-value store
   type App struct {
       DB     *sql.DB
       Cache  *redis.Client
       Config Config
   }

   func main() {
       app := &App{...}
       r := gin.Default()

       // Closure captures app — idiomatic for small applications
       r.GET("/users", func(c *gin.Context) {
           rows, _ := app.DB.Query("SELECT ...")
       })
   }

   // Rust: define a typed state struct with Clone
   // src/state.rs
   //
   // All fields must be Clone because Axum clones AppState for each request.
   // Arc<T> is the standard way to share non-Clone or expensive-to-clone data.
   // Tokio's PgPool (from sqlx) is already Arc-wrapped internally, so it is
   // cheap to clone and safe to share across tasks.
   use tokio::sync::mpsc;
   use crate::worker::scheduler::Job;

   #[derive(Clone)]
   pub struct AppState {
       // Sender is Clone — cloning creates another handle to the same channel.
       pub job_sender: mpsc::Sender<Job>,
       pub config: AppConfig,
       // Example: pub db: sqlx::PgPool,
       // Example: pub cache: Arc<redis::Client>,
   }

   #[derive(Clone)]
   pub struct AppConfig {
       pub environment: String,
       pub api_key: String,
   }

8. Error Handling {#error-handling}

Gin's Imperative Error Model

In Gin, error handling is a series of if err != nil checks followed by early returns with c.AbortWithStatusJSON. The pattern is familiar to every Go developer, but it has a subtle limitation: the error response format is determined at each call site. If ten different handlers return errors, each one decides independently how to format the JSON. Centralising error formatting requires a custom middleware that reads from c.Errors, or a shared helper function that everyone must remember to call.

   // Gin: error handling at each call site with AbortWithStatusJSON
   func getUser(c *gin.Context) {
       id := c.Param("id")
       user, err := db.FindUser(id)
       if err != nil {
           if errors.Is(err, ErrNotFound) {
               c.AbortWithStatusJSON(404, gin.H{"error": "not found"})
               return
           }
           c.AbortWithStatusJSON(500, gin.H{"error": "internal error"})
           return
       }
       c.JSON(200, user)
   }

Rust + Axum: The `IntoResponse` Error Type

Axum's error handling model leverages Rust's Result type and the IntoResponse trait to centralise error formatting automatically. You define a custom error enum for your application, implement IntoResponse on it once, and then every handler that returns Result<T, AppError> automatically uses your centralised error formatting logic. There is no AbortWithStatusJSON and no need to remember to call a helper — the type system ensures that every error path produces the same structured response.

The thiserror crate provides derive macros that generate Display and Error implementations from your enum definition, eliminating boilerplate. The #[from] attribute on a variant automatically generates a From implementation, allowing you to use the ? operator to convert lower-level errors into your application error type.

   // src/error.rs
   //
   // Define your application error enum once.
   // Implement IntoResponse once.
   // Every handler that returns Result<T, AppError> uses this automatically.
   // This is the Axum equivalent of a centralised Gin error middleware,
   // but enforced by the type system rather than by convention.
   use axum::{
       response::{IntoResponse, Response},
       Json,
       http::StatusCode,
   };
   use thiserror::Error;

   #[derive(Debug, Error)]
   pub enum AppError {
       #[error("not found: {0}")]
       NotFound(String),

       #[error("unauthorized")]
       Unauthorized,

       #[error("bad request: {0}")]
       BadRequest(String),

       // The #[from] attribute generates From<anyhow::Error> for AppError.
       // This lets you use ? on any anyhow::Result inside a handler.
       #[error("internal error")]
       Internal(#[from] anyhow::Error),
   }

   // This implementation is called automatically whenever a handler returns
   // Err(AppError::SomeVariant). You define the mapping from error variant
   // to HTTP status code and response body once, here, and it applies everywhere.
   impl IntoResponse for AppError {
       fn into_response(self) -> Response {
           let (status, message) = match &self {
               AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
               AppError::Unauthorized => (
                   StatusCode::UNAUTHORIZED,
                   "unauthorized".to_string(),
               ),
               AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
               AppError::Internal(e) => {
                   // Log the full internal error but do not expose it to the client.
                   tracing::error!("internal error: {:?}", e);
                   (
                       StatusCode::INTERNAL_SERVER_ERROR,
                       "internal server error".to_string(),
                   )
               }
           };

           let body = Json(serde_json::json!({
               "error": message,
               "status": status.as_u16(),
           }));

           (status, body).into_response()
       }
   }

   // Usage in a handler. The return type is the self-documenting contract.
   // Ok(T) flows through normally. Err(AppError) triggers into_response() above.
   // The ? operator on any Result<T, AppError> propagates errors automatically.
   // src/handlers/users.rs
   use crate::error::AppError;

   pub async fn get_user(
       Path(id): Path<String>,
   ) -> Result<Json<serde_json::Value>, AppError> {
       if id == "0" {
           // This is the equivalent of c.AbortWithStatusJSON(404, ...) in Gin,
           // but it composes with the rest of the function via the type system.
           return Err(AppError::NotFound(format!("user {} not found", id)));
       }

       // Imaginary DB call: db.find_user(&id).await?
       // The ? converts any DB error into AppError::Internal via From<anyhow::Error>.

       Ok(Json(serde_json::json!({ "id": id, "name": "Alice" })))
   }

9. Full Working Example {#full-example}

The following is the complete compilable project. Every file shown here is necessary. The structure separates concerns in a way that scales beyond a tutorial into a real application.

   rust-server/
   ├── Cargo.toml
   └── src/
       ├── main.rs
       ├── state.rs
       ├── error.rs
       ├── routes/
       │   └── mod.rs
       ├── handlers/
       │   ├── mod.rs
       │   ├── health.rs
       │   ├── users.rs
       │   └── jobs.rs
       ├── middleware/
       │   ├── mod.rs
       │   ├── auth.rs
       │   └── timing.rs
       └── worker/
           ├── mod.rs
           └── scheduler.rs

src/state.rs

   use tokio::sync::mpsc;
   use crate::worker::scheduler::Job;

   #[derive(Clone)]
   pub struct AppState {
       pub job_sender: mpsc::Sender<Job>,
   }

src/error.rs

   use axum::{response::{IntoResponse, Response}, Json, http::StatusCode};
   use thiserror::Error;

   #[derive(Debug, Error)]
   pub enum AppError {
       #[error("not found: {0}")]
       NotFound(String),
       #[error("unauthorized")]
       Unauthorized,
       #[error("bad request: {0}")]
       BadRequest(String),
       #[error("internal error")]
       Internal(String),
   }

   impl IntoResponse for AppError {
       fn into_response(self) -> Response {
           let (status, message) = match &self {
               AppError::NotFound(m) => (StatusCode::NOT_FOUND, m.clone()),
               AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized".into()),
               AppError::BadRequest(m) => (StatusCode::BAD_REQUEST, m.clone()),
               AppError::Internal(m) => (StatusCode::INTERNAL_SERVER_ERROR, m.clone()),
           };
           (status, Json(serde_json::json!({ "error": message }))).into_response()
       }
   }

src/middleware/mod.rs

   pub mod auth;
   pub mod timing;

src/middleware/timing.rs

   use axum::{extract::Request, middleware::Next, response::Response};
   use std::time::Instant;
   use tracing::info;

   pub async fn timing_middleware(req: Request, next: Next) -> Response {
       let start = Instant::now();
       let method = req.method().clone();
       let uri = req.uri().clone();
       let response = next.run(req).await;
       info!(
           method = %method,
           uri = %uri,
           status = response.status().as_u16(),
           duration_ms = start.elapsed().as_millis(),
           "request completed"
       );
       response
   }

src/middleware/auth.rs

   use axum::{
       extract::Request, middleware::Next,
       response::{IntoResponse, Response},
       Json, http::StatusCode,
   };

   #[derive(Clone)]
   pub struct AuthenticatedUser {
       pub id: String,
       pub token: String,
   }

   pub async fn auth_middleware(mut req: Request, next: Next) -> Response {
       let token = req.headers()
           .get("Authorization")
           .and_then(|v| v.to_str().ok())
           .map(|s| s.to_string());

       match token {
           None | Some(ref t) if t.is_empty() => {
               return (
                   StatusCode::UNAUTHORIZED,
                   Json(serde_json::json!({ "error": "unauthorized" })),
               ).into_response();
           }
           Some(token) => {
               req.extensions_mut().insert(AuthenticatedUser {
                   id: "user-123".to_string(),
                   token,
               });
           }
       }

       next.run(req).await
   }

src/handlers/mod.rs

   pub mod health;
   pub mod users;
   pub mod jobs;

src/handlers/health.rs

   use axum::Json;

   pub async fn ping() -> Json<serde_json::Value> {
       axum::Json(serde_json::json!({ "message": "pong" }))
   }

src/handlers/users.rs

   use axum::{extract::Path, Json, http::StatusCode};
   use crate::error::AppError;

   pub async fn get_user(
       Path(id): Path<String>,
   ) -> Result<Json<serde_json::Value>, AppError> {
       if id == "0" {
           return Err(AppError::NotFound(format!("user {id} not found")));
       }
       Ok(Json(serde_json::json!({ "id": id, "name": "Alice" })))
   }

   pub async fn list_users() -> Json<serde_json::Value> {
       Json(serde_json::json!({ "users": [] }))
   }

src/handlers/jobs.rs

   use axum::{extract::State, Json, http::StatusCode};
   use tokio::sync::oneshot;
   use uuid::Uuid;
   use crate::{state::AppState, worker::scheduler::{Job, JobResult}};
   use serde::Deserialize;

   #[derive(Deserialize)]
   pub struct CreateJobRequest {
       pub payload: serde_json::Value,
   }

   pub async fn submit_job(
       State(state): State<AppState>,
       Json(body): Json<CreateJobRequest>,
   ) -> StatusCode {
       let job = Job {
           id: Uuid::new_v4().to_string(),
           payload: body.payload,
           reply: None,
       };
       match state.job_sender.send(job).await {
           Ok(_) => StatusCode::ACCEPTED,
           Err(_) => StatusCode::SERVICE_UNAVAILABLE,
       }
   }

src/worker/mod.rs

   pub mod scheduler;

src/worker/scheduler.rs

   use tokio::sync::{mpsc, oneshot};
   use tokio::select;
   use tracing::{info, warn};

   #[derive(Debug)]
   pub struct Job {
       pub id: String,
       pub payload: serde_json::Value,
       pub reply: Option<oneshot::Sender<JobResult>>,
   }

   #[derive(Debug)]
   pub struct JobResult {
       pub success: bool,
       pub message: String,
   }

   pub struct Scheduler {
       pub sender: mpsc::Sender<Job>,
   }

   impl Scheduler {
       pub fn new(buffer_size: usize) -> (Self, mpsc::Receiver<Job>) {
           let (sender, receiver) = mpsc::channel(buffer_size);
           (Self { sender }, receiver)
       }
   }

   pub async fn run_scheduler(
       mut receiver: mpsc::Receiver<Job>,
       mut shutdown: tokio::sync::broadcast::Receiver<()>,
   ) {
       info!("scheduler started");
       loop {
           select! {
               biased;
               _ = shutdown.recv() => {
                   info!("scheduler shutting down");
                   break;
               }
               job = receiver.recv() => {
                   match job {
                       Some(j) => process_job(j).await,
                       None => { warn!("all senders dropped"); break; }
                   }
               }
           }
       }
       info!("scheduler stopped");
   }

   async fn process_job(job: Job) {
       info!(job_id = %job.id, "processing");
       tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;
       let result = JobResult { success: true, message: format!("done: {}", job.id) };
       if let Some(reply) = job.reply {
           let _ = reply.send(result);
       }
   }

src/routes/mod.rs

   use axum::{middleware, routing::{get, post}, Router};
   use tower_http::trace::TraceLayer;
   use crate::{
       handlers::{health, jobs, users},
       middleware::{auth::auth_middleware, timing::timing_middleware},
       state::AppState,
   };

   pub fn build_router(state: AppState) -> Router {
       let protected = Router::new()
           .route("/users", get(users::list_users))
           .route("/users/:id", get(users::get_user))
           .route("/jobs", post(jobs::submit_job))
           .layer(middleware::from_fn(auth_middleware));

       Router::new()
           .route("/ping", get(health::ping))
           .merge(protected)
           .layer(middleware::from_fn(timing_middleware))
           .layer(TraceLayer::new_for_http())
           .with_state(state)
   }

src/main.rs

   mod error;
   mod handlers;
   mod middleware;
   mod routes;
   mod state;
   mod worker;

   use std::net::SocketAddr;
   use tokio::{net::TcpListener, sync::broadcast};
   use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
   use state::AppState;
   use worker::scheduler::Scheduler;

   #[tokio::main]
   async fn main() {
       tracing_subscriber::registry()
           .with(tracing_subscriber::EnvFilter::new(
               std::env::var("RUST_LOG")
                   .unwrap_or_else(|_| "rust_server=debug,tower_http=debug".into()),
           ))
           .with(tracing_subscriber::fmt::layer())
           .init();

       let (shutdown_tx, shutdown_rx) = broadcast::channel::<()>(1);
       let (scheduler, receiver) = Scheduler::new(100);

       tokio::spawn(worker::scheduler::run_scheduler(receiver, shutdown_rx));

       let state = AppState {
           job_sender: scheduler.sender,
       };

       let app = routes::build_router(state);
       let addr = SocketAddr::from(([0, 0, 0, 0], 8080));
       let listener = TcpListener::bind(addr).await.unwrap();

       tracing::info!("listening on {}", addr);

       axum::serve(listener, app)
           .with_graceful_shutdown(async move {
               tokio::signal::ctrl_c().await.unwrap();
               tracing::info!("shutting down");
               let _ = shutdown_tx.send(());
           })
           .await
           .unwrap();
   }

10. Gotchas & Common Problems {#gotchas}

The following table consolidates every significant pitfall covered in this guide along with the ones that most commonly appear in Axum codebases written by developers coming from Go. Each row maps a symptom you will encounter to its root cause and a concrete fix.

#	Problem	Symptom	Fix
1	Version mismatches in the Hyper/Axum/tower-http triad	Cryptic trait bound errors mentioning `hyper::body::Body`	Pin all three versions explicitly; check axum changelog before upgrading
2	`axum::Server` removed in 0.7	`error[E0603]: module 'Server' is private` or not found	Use `TcpListener::bind().await` and `axum::serve()`
3	Extractor ordering — body extractor not last	Missing trait implementation on handler function	Move `Json<T>`, `Bytes`, `String`, or `Form<T>` to be the final function parameter
4	Layer ordering reversed vs Gin	Wrong middleware executes first; auth bypassed	Remember: last `.layer()` call = outermost = first to run on request
5	Blocking in async context	Runtime stalls; timeouts under moderate load	Use `tokio::sync`, `tokio::time`, `tokio::fs`; use `spawn_blocking` for CPU/blocking I/O
6	`AppState` does not implement `Clone`	Compile error when calling `.with_state()`	Derive `Clone`; wrap non-Clone fields in `Arc<T>`
7	Capturing environment in async middleware closures	`cannot move out of shared reference` or lifetime errors	Clone the `Arc` outside the closure, clone again inside the `async move` block
8	`select!` fairness causing starvation	Shutdown signals ignored under high job load	Use `biased;` directive so shutdown branch is checked first in every iteration

Deeper Dive: Gotcha 6 and 7

These two gotchas are closely related and frequently occur together when engineers first try to pass configuration or database connections through middleware. The root cause is that Axum requires AppState to be Clone because it clones the state for each incoming request, and Rust's ownership rules require you to be explicit about how data is shared across async boundaries.

   // WRONG: State without Clone will not compile.
   // Axum calls state.clone() internally — if Clone is not derived, the compiler
   // tells you about a missing trait bound on the with_state() call, which is
   // confusing because the error points at with_state, not at your struct.
   #[derive(Debug)]
   struct AppState {
       counter: std::sync::Mutex<u64>,  // Mutex is not Clone
   }

   // RIGHT: Wrap non-Clone data in Arc so cloning is cheap and safe.
   // Arc::clone() increments a reference count — it does not copy the data.
   // Tokio's Mutex is used instead of std's because it is async-aware.
   #[derive(Debug, Clone)]
   struct AppState {
       counter: std::sync::Arc<tokio::sync::Mutex<u64>>,
   }

   // WRONG: Capturing state by reference in an async middleware closure.
   // Async closures must be 'static — they cannot hold references to
   // local variables because the closure may outlive the stack frame.
   let config = load_config();  // Config is not Clone or Arc
   let mw = move |req: Request, next: Next| async {
       println!("{}", config.value);  // Error: config may not live long enough
       next.run(req).await
   };

   // RIGHT: Wrap in Arc first, then clone the Arc into the closure.
   // The Arc clone is cheap. Each invocation of the closure gets its own
   // Arc clone, which points to the same underlying Config allocation.
   let config = std::sync::Arc::new(load_config());
   let mw = {
       let config = config.clone();          // Clone Arc for the outer closure
       move |req: Request, next: Next| {
           let config = config.clone();      // Clone Arc for each async invocation
           async move {
               println!("{}", config.value);
               next.run(req).await
           }
       }
   };

When to Use `from_fn` vs Implementing `Layer` Manually

Most engineers writing application code should use from_fn for the entirety of their middleware needs. The manual Layer + Service implementation path exists for library authors and for cases where you need access to Tower's backpressure mechanism (poll_ready) or where you need to modify the response type in a way that from_fn does not support.

   // Use axum::middleware::from_fn when:
   //   ✓ You need to inspect or modify request headers
   //   ✓ You need to short-circuit with an early response (auth, rate limiting)
   //   ✓ You need to time or log requests
   //   ✓ You need to inject values into request extensions
   //   ✓ You need to read or modify response headers or status
   //   ✓ 95% of production application middleware falls here

   // Implement tower::Layer + tower::Service manually when:
   //   ✓ You are writing a reusable library crate (not application code)
   //   ✓ You need poll_ready() for backpressure-aware behaviour
   //   ✓ You need to wrap the response Future itself for streaming
   //   ✓ You need to inspect the inner Service type at layer construction time

11. Cheat Sheet {#cheat-sheet}

This reference table provides the complete vocabulary mapping from Gin to Axum for daily use. Bookmark this section.

Go + Gin	Rust + Axum
`gin.Default()`	`Router::new()` + `TraceLayer` + timing middleware
`gin.New()`	`Router::new()`
`r.GET("/path", handler)`	`.route("/path", get(handler))`
`r.POST("/path", handler)`	`.route("/path", post(handler))`
`r.Group("/prefix")`	`Router::new().nest("/prefix", sub_router)`
`r.Use(middleware)`	`.layer(from_fn(middleware))`
`group.Use(middleware)`	`sub_router.layer(from_fn(middleware))`
`c.Param("id")`	`Path(id): Path<String>`
`c.Query("q")`	`Query(p): Query<MyParams>` with `Option<String>`
`c.DefaultQuery("page", "1")`	`#[serde(default = "fn_name")]` on struct field
`c.GetHeader("Authorization")`	`headers: HeaderMap` then `headers.get("...")`
`c.ShouldBindJSON(&v)`	`Json(body): Json<MyStruct>` (must be last)
`c.JSON(200, gin.H{})`	`Json(json!({}))` or `(StatusCode::OK, Json(...))`
`c.Status(204)`	`StatusCode::NO_CONTENT`
`c.Header("key", "value")`	Return tuple `(StatusCode, HeaderMap, Json<T>)`
`c.Set("key", val)`	`req.extensions_mut().insert(MyTypedValue)`
`c.Get("key")`	`Extension(val): Extension<MyTypedValue>`
`c.AbortWithStatusJSON(401, ...)`	`return (StatusCode::UNAUTHORIZED, Json(...)).into_response()`
`c.Next()`	`next.run(req).await`
`make(chan Job, 100)`	`mpsc::channel::<Job>(100)`
`go func() { for { select {} } }()`	`tokio::spawn(async { loop { select! {} } })`
`context.WithCancel`	`broadcast::channel` + `graceful_shutdown`
`select { case <-ctx.Done(): }`	`select! { _ = shutdown.recv() => {} }`
`select { case ch <- v: default: }`	`sender.try_send(v)` — returns `Err` if full
`ch <- v` (blocking send)	`sender.send(v).await`
`result := <-doneCh`	`reply_rx.await`
`errors.Is(err, ErrNotFound)`	`AppError::NotFound(...)` via `?` operator
`http.StatusOK`	`StatusCode::OK`
`http.StatusCreated`	`StatusCode::CREATED`
`http.StatusNoContent`	`StatusCode::NO_CONTENT`
`http.StatusUnauthorized`	`StatusCode::UNAUTHORIZED`
`http.StatusInternalServerError`	`StatusCode::INTERNAL_SERVER_ERROR`

Final Thoughts

The transition from Gin to Axum is not a syntax translation exercise. It is a migration from an imperative, runtime-checked programming model to a compositional, compile-time-verified one. Every pattern you relied on in Gin has a precise equivalent in Axum — the handler chain, the shared context, the route groups, the work queue — but the mechanism that implements each pattern is grounded in Rust's type system rather than in runtime conventions.

The three investments that will pay dividends most quickly are these: first, spend time reading the Tower documentation to understand Service and Layer, even if you only ever use from_fn. Comprehending what from_fn wraps makes every compiler error in this space legible. Second, embrace the Result<T, AppError> return type across all of your handlers and define your AppError::IntoResponse implementation early, before you write any domain logic. This single architectural decision eliminates the entire class of inconsistent error response formatting that plagues Gin applications at scale. Third, never fight the borrow checker in async contexts — when you see lifetime errors in middleware or handlers, the answer is almost always an Arc::clone() before the async boundary, not an attempt to pass references across it.

Axum's surface area is intentionally smaller than Gin's. It provides the composition primitives and defers the higher-level decisions to you. The crates in the Tower and tower-http ecosystem fill the gap with production-quality implementations of the middleware that Gin provides out of the box. Once the compositional model becomes natural, you will find it more expressive than Gin's imperative model — and the compiler will catch entire classes of configuration bugs that in a Go service would only surface in production under load.

Basement Water Monitor Circuit in Go, Rust and C

Andrei Merlescu — Sun, 31 May 2026 01:31:54 +0000

Together in this document we're going to build out through concept a circuit that can be used for constructing a basement water monitoring device - from scratch, built in Go, Rust and C so that you can see the differences in how these languages express themselves for the same task. Some of them are easier than others, and some of them are clear long term historical winners for a reason given any degree of complexity that may arise related to the construction of any new circuitry itself.

Structural Comparison between Rust and C

Concern          Rust / Embassy              C / no RTOS
─────────────────────────────────────────────────────────────
Concurrency      6 async tasks, Embassy      1 loop, manual
                 schedules cooperatively     timestamp polling

Data safety      Mutex<SensorState>,         volatile struct,
                 compiler enforces locking   convention only

DHT22 timing     PIO hardware offload,       Busy-wait loops,
                 CPU free during read        CPU blocked 5ms

Memory safety    heapless::String<N>,        char[N], silent
                 overflow = compile error    overflow = UB

Connection mgmt  TcpSocket, linear code,     lwIP callbacks,
                 reads top to bottom         scattered state machine

Cleanup          Drop trait, automatic       free() manual,
                 cannot be forgotten         easy to forget

WiFi connect     .await, yields executor     blocks CPU entirely
                 during 30s wait             for up to 30s

This is what we are going to build:

Internet
    |
 [Router]
    |
[Pico W] <-- WiFi
    |
    +---> [Water Sensor] basement floor
    +---> [DHT22]        humidity/temp
    +---> [PIR]          motion
    +---> [MQ-7]         CO detector
    +---> [Relay] -----> [Sump Pump]
    +---> [Buzzer]       local alarm
    +---> [OLED]         local display
    |
[ESP32-CAM] <-- basement camera, streams to Pico W HTTP server
    |
 Browser: http://pico.local/
   - sensor readings
   - camera feed
   - alert history

Rust Directory Structure

basement-monitor/
├── Cargo.toml
├── build.rs
├── memory.x          ← tells linker where flash/RAM live on RP2040
└── src/
    ├── main.rs       ← entry point, spawns all tasks
    ├── sensors.rs    ← DHT22, water, PIR, MQ7
    ├── display.rs    ← SSD1306 OLED
    ├── alarm.rs      ← buzzer + relay logic
    ├── wifi.rs       ← Pico W network setup
    └── http.rs       ← HTTP server, serves sensor JSON + camera

C Directory Structure

basement-monitor-c/
├── CMakeLists.txt
├── pico_sdk_import.cmake
├── src/
│   ├── main.c
│   ├── sensors.c / sensors.h
│   ├── display.c / display.h
│   ├── alarm.c   / alarm.h
│   ├── wifi.c    / wifi.h
│   └── http.c    / http.h
└── lib/
    └── ssd1306/  ← third party OLED driver

Go Directory Structure

basement-monitor-tinygo/
├── go.mod
├── main.go
├── sensors/
│   ├── dht22.go
│   ├── water.go
│   ├── pir.go
│   └── co.go
├── display/
│   └── oled.go
├── alarm/
│   └── alarm.go
├── wifi/
│   └── wifi.go
└── http/
    └── server.go

Trinity Comparison of Go <> Rust <> C Project Directory Structures

We have sensors.rs and sensors.c which are both single files, but we have a package called sensors that places the implementation of each dht22, water, pir, and co sensors individually. How these are split out into their respective concerns matters because go packages are reusable resources across Go programs and technically speaking, why would this type of structure matter to an on-device program? The code self explains it and we'll get to that.

Same thing for display, the alarm, the wifi chip, and the http server that provides a status page. This kind of a breakdown makes the comparison of the implementation of this across these three languages something that is pretty unique for a case study into Rust from Go from a Computer Engineer who has been a self-taught 21+ year professional Staff DevOps Engineer using Go to build multi-region global cloud architectures for SurgePays and WB Games.

Each of the implementations of the project have generalized boilerplate overhead that is language specific. Each have their own Makefile and this is where we'll begin...

# basement-monitor-tinygo/Makefile

TARGET     := pico-w
BINARY     := basement-monitor
OPT        := z
PORT       ?= $(shell ls /dev/tty.usbmodem* 2>/dev/null | head -1)

# Colors for terminal output
RED    := \033[0;31m
GREEN  := \033[0;32m
YELLOW := \033[0;33m
BLUE   := \033[0;34m
RESET  := \033[0m

.PHONY: all build clean run flash monitor fmt vet size help

all: build

## build: compile and produce .uf2 file
build:
    @echo "$(BLUE)[TINYGO]$(RESET) Building $(BINARY) for $(TARGET)..."
    @tinygo build \
        -target=$(TARGET) \
        -opt=$(OPT) \
        -o $(BINARY).uf2 \
        .
    @echo "$(GREEN)[OK]$(RESET) Built $(BINARY).uf2"
    @ls -lh $(BINARY).uf2

## flash: build and flash directly to connected Pico W
flash: build
    @echo "$(BLUE)[TINYGO]$(RESET) Flashing to $(TARGET)..."
    @tinygo flash \
        -target=$(TARGET) \
        -opt=$(OPT) \
        .
    @echo "$(GREEN)[OK]$(RESET) Flashed successfully"

## run: flash and immediately open serial monitor
run: flash monitor

## monitor: open serial monitor (after flashing separately)
monitor:
    @echo "$(BLUE)[TINYGO]$(RESET) Opening serial monitor on $(PORT)..."
    @if [ -z "$(PORT)" ]; then \
        echo "$(RED)[ERR]$(RESET) No USB serial port found."; \
        echo "      Is the Pico W connected and flashed?"; \
        exit 1; \
    fi
    @tinygo monitor -target=$(TARGET)

## size: show binary size breakdown by package
size:
    @echo "$(BLUE)[TINYGO]$(RESET) Binary size analysis:"
    @tinygo build \
        -target=$(TARGET) \
        -opt=$(OPT) \
        -size=full \
        .

## fmt: format all Go source files
fmt:
    @echo "$(BLUE)[TINYGO]$(RESET) Formatting source..."
    @gofmt -w .
    @echo "$(GREEN)[OK]$(RESET) Done"

## vet: run go vet (catches common errors)
vet:
    @echo "$(BLUE)[TINYGO]$(RESET) Running vet..."
    @tinygo vet -target=$(TARGET) .
    @echo "$(GREEN)[OK]$(RESET) No issues found"

## test: run tests on host (not on device)
test:
    @echo "$(BLUE)[TINYGO]$(RESET) Running host tests..."
    @go test ./...

## clean: remove build artifacts
clean:
    @echo "$(YELLOW)[CLEAN]$(RESET) Removing build artifacts..."
    @rm -f $(BINARY).uf2
    @rm -f $(BINARY).elf
    @rm -f $(BINARY).hex
    @rm -f $(BINARY).bin
    @echo "$(GREEN)[OK]$(RESET) Clean complete"

## help: show this help
help:
    @echo ""
    @echo "$(BLUE)Basement Monitor — TinyGo$(RESET)"
    @echo "Target: $(TARGET)"
    @echo ""
    @grep -E '^##' Makefile | sed 's/## /  make /'
    @echo ""

Rust

# basement-monitor-rust/Makefile

BINARY     := basement-monitor
TARGET     := thumbv6m-none-eabi
CHIP       := RP2040
PROBE      ?= auto
PORT       ?= $(shell ls /dev/tty.usbmodem* 2>/dev/null | head -1)

RED    := \033[0;31m
GREEN  := \033[0;32m
YELLOW := \033[0;33m
BLUE   := \033[0;34m
RESET  := \033[0m

.PHONY: all build build-release clean run flash monitor \
       fmt clippy test size doc expand help

all: build

## build: debug build (faster compile, larger binary, includes debug symbols)
build:
    @echo "$(BLUE)[RUST ]$(RESET) Building $(BINARY) (debug)..."
    @cargo build --target $(TARGET)
    @echo "$(GREEN)[OK]$(RESET) Debug build complete"
    @ls -lh target/$(TARGET)/debug/$(BINARY)

## build-release: optimized build for flashing to device
build-release:
    @echo "$(BLUE)[RUST ]$(RESET) Building $(BINARY) (release)..."
    @cargo build \
        --target $(TARGET) \
        --release
    @echo "$(GREEN)[OK]$(RESET) Release build complete"
    @ls -lh target/$(TARGET)/release/$(BINARY)

## uf2: produce .uf2 drag-and-drop file from release build
uf2: build-release
    @echo "$(BLUE)[RUST ]$(RESET) Converting to UF2..."
    @elf2uf2-rs \
        target/$(TARGET)/release/$(BINARY) \
        $(BINARY).uf2
    @echo "$(GREEN)[OK]$(RESET) $(BINARY).uf2 ready"
    @ls -lh $(BINARY).uf2

## flash: build release and flash via cargo-flash (requires probe-rs)
flash: build-release
    @echo "$(BLUE)[RUST ]$(RESET) Flashing via probe-rs..."
    @cargo flash \
        --target $(TARGET) \
        --release \
        --chip $(CHIP) \
        --probe $(PROBE)
    @echo "$(GREEN)[OK]$(RESET) Flashed successfully"

## run: flash and open RTT monitor (defmt logging via probe)
run: flash monitor

## monitor: open defmt RTT log monitor (requires probe-rs + probe connected)
monitor:
    @echo "$(BLUE)[RUST ]$(RESET) Opening defmt monitor..."
    @cargo embed \
        --target $(TARGET) \
        --release \
        --chip $(CHIP)

## monitor-serial: open plain serial monitor (USB serial fallback)
monitor-serial:
    @echo "$(BLUE)[RUST ]$(RESET) Opening serial monitor on $(PORT)..."
    @if [ -z "$(PORT)" ]; then \
        echo "$(RED)[ERR]$(RESET) No USB serial port found."; \
        exit 1; \
    fi
    @screen $(PORT) 115200

## fmt: format all Rust source files
fmt:
    @echo "$(BLUE)[RUST ]$(RESET) Formatting source..."
    @cargo fmt
    @echo "$(GREEN)[OK]$(RESET) Done"

## fmt-check: check formatting without modifying (for CI)
fmt-check:
    @echo "$(BLUE)[RUST ]$(RESET) Checking formatting..."
    @cargo fmt --check
    @echo "$(GREEN)[OK]$(RESET) Formatting OK"

## clippy: run Clippy linter — catches common Rust mistakes
clippy:
    @echo "$(BLUE)[RUST ]$(RESET) Running Clippy..."
    @cargo clippy \
        --target $(TARGET) \
        -- -D warnings
    @echo "$(GREEN)[OK]$(RESET) No Clippy warnings"

## test: run unit tests on host (not on device)
# Tests that don't use hardware peripherals can run on your laptop.
# Hardware-dependent tests require a device and cargo-test-embedded.
test:
    @echo "$(BLUE)[RUST ]$(RESET) Running host tests..."
    @cargo test --lib
    @echo "$(GREEN)[OK]$(RESET) Tests passed"

## size: show binary size by section and crate
size: build-release
    @echo "$(BLUE)[RUST ]$(RESET) Binary size analysis:"
    @cargo size \
        --target $(TARGET) \
        --release \
        -- -A
    @echo ""
    @echo "$(BLUE)[RUST ]$(RESET) Size by crate:"
    @cargo bloat \
        --target $(TARGET) \
        --release \
        --crates

## doc: build and open documentation
doc:
    @echo "$(BLUE)[RUST ]$(RESET) Building docs..."
    @cargo doc --open

## expand: show macro expansion (useful for Embassy task macros)
expand:
    @echo "$(BLUE)[RUST ]$(RESET) Expanding macros in main.rs..."
    @cargo expand --target $(TARGET)

## clean: remove all build artifacts
clean:
    @echo "$(YELLOW)[CLEAN]$(RESET) Removing build artifacts..."
    @cargo clean
    @rm -f $(BINARY).uf2
    @rm -f $(BINARY).elf
    @echo "$(GREEN)[OK]$(RESET) Clean complete"

## help: show this help
help:
    @echo ""
    @echo "$(BLUE)Basement Monitor — Rust / Embassy$(RESET)"
    @echo "Target: $(TARGET)  Chip: $(CHIP)"
    @echo ""
    @grep -E '^##' Makefile | sed 's/## /  make /'
    @echo ""
    @echo "$(YELLOW)Note:$(RESET) 'make flash' and 'make monitor' require"
    @echo "      a debug probe (e.g. Raspberry Pi Debug Probe)."
    @echo "      Use 'make uf2' for drag-and-drop flashing instead."
    @echo ""

# basement-monitor-c/Makefile

BINARY     := basement-monitor
BUILD_DIR  := build
PICO_SDK   ?= $(HOME)/pico/pico-sdk
PORT       ?= $(shell ls /dev/tty.usbmodem* 2>/dev/null | head -1)
JOBS       ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)

RED    := \033[0;31m
GREEN  := \033[0;32m
YELLOW := \033[0;33m
BLUE   := \033[0;34m
RESET  := \033[0m

.PHONY: all build clean run flash monitor \
       configure reconfigure size format \
       check-sdk check-tools help

all: build

## build: configure (if needed) and compile
build: check-sdk check-tools configure
    @echo "$(BLUE)[C    ]$(RESET) Building $(BINARY)..."
    @cmake \
        --build $(BUILD_DIR) \
        --parallel $(JOBS)
    @echo "$(GREEN)[OK]$(RESET) Build complete"
    @ls -lh $(BUILD_DIR)/$(BINARY).uf2

## configure: run CMake to generate build system
# Only runs if build/ doesn't exist yet.
# Use 'make reconfigure' to force a fresh CMake run.
configure:
    @if [ ! -f "$(BUILD_DIR)/Makefile" ] && [ ! -f "$(BUILD_DIR)/build.ninja" ]; then \
        echo "$(BLUE)[C    ]$(RESET) Configuring with CMake..."; \
        cmake \
            -S . \
            -B $(BUILD_DIR) \
            -DPICO_SDK_PATH=$(PICO_SDK) \
            -DCMAKE_BUILD_TYPE=Release \
            -DPICO_BOARD=pico_w; \
        echo "$(GREEN)[OK]$(RESET) Configuration complete"; \
    fi

## reconfigure: force fresh CMake configuration
reconfigure:
    @echo "$(YELLOW)[CMAKE]$(RESET) Forcing reconfiguration..."
    @rm -rf $(BUILD_DIR)
    @$(MAKE) configure

## flash: build and copy .uf2 to Pico W mounted as USB drive
# Put Pico W in BOOTSEL mode: hold BOOTSEL button, plug in USB, release.
# The board mounts as a USB drive named RPI-RP2.
flash: build
    @echo "$(BLUE)[C    ]$(RESET) Looking for RPI-RP2 mount point..."
    @MOUNT=""; \
    for path in \
        /Volumes/RPI-RP2 \
        /media/$$USER/RPI-RP2 \
        /mnt/RPI-RP2; do \
        if [ -d "$$path" ]; then \
            MOUNT=$$path; \
            break; \
        fi; \
    done; \
    if [ -z "$$MOUNT" ]; then \
        echo "$(RED)[ERR]$(RESET) RPI-RP2 not found."; \
        echo "      Hold BOOTSEL, plug in USB, release BOOTSEL."; \
        exit 1; \
    fi; \
    echo "$(BLUE)[C    ]$(RESET) Copying .uf2 to $$MOUNT ..."; \
    cp $(BUILD_DIR)/$(BINARY).uf2 $$MOUNT/; \
    echo "$(GREEN)[OK]$(RESET) Flashed — board will reboot automatically"

## flash-openocd: flash via OpenOCD + SWD debug probe
flash-openocd: build
    @echo "$(BLUE)[C    ]$(RESET) Flashing via OpenOCD..."
    @openocd \
        -f interface/cmsis-dap.cfg \
        -f target/rp2040.cfg \
        -c "adapter speed 5000" \
        -c "program $(BUILD_DIR)/$(BINARY).elf verify reset exit"
    @echo "$(GREEN)[OK]$(RESET) Flashed via OpenOCD"

## run: flash (BOOTSEL method) and open serial monitor
run: flash monitor

## monitor: open serial monitor to see printf output
monitor:
    @echo "$(BLUE)[C    ]$(RESET) Opening serial monitor on $(PORT)..."
    @if [ -z "$(PORT)" ]; then \
        echo "$(RED)[ERR]$(RESET) No USB serial port found."; \
        echo "      Is the Pico W connected and running?"; \
        exit 1; \
    fi
    @screen $(PORT) 115200

## size: show binary size by section
size: build
    @echo "$(BLUE)[C    ]$(RESET) Binary size breakdown:"
    @arm-none-eabi-size \
        --format=Berkeley \
        $(BUILD_DIR)/$(BINARY).elf
    @echo ""
    @echo "$(BLUE)[C    ]$(RESET) Section detail:"
    @arm-none-eabi-size \
        --format=SysV \
        $(BUILD_DIR)/$(BINARY).elf

## format: format all C source files with clang-format
format:
    @echo "$(BLUE)[C    ]$(RESET) Formatting source..."
    @find src/ -name '*.c' -o -name '*.h' | \
        xargs clang-format \
            --style='{BasedOnStyle: LLVM, IndentWidth: 4}' \
            -i
    @echo "$(GREEN)[OK]$(RESET) Done"

## format-check: check formatting without modifying (for CI)
format-check:
    @echo "$(BLUE)[C    ]$(RESET) Checking formatting..."
    @find src/ -name '*.c' -o -name '*.h' | \
        xargs clang-format \
            --style='{BasedOnStyle: LLVM, IndentWidth: 4}' \
            --dry-run \
            --Werror
    @echo "$(GREEN)[OK]$(RESET) Formatting OK"

## clean: remove build directory
clean:
    @echo "$(YELLOW)[CLEAN]$(RESET) Removing $(BUILD_DIR)/..."
    @rm -rf $(BUILD_DIR)
    @echo "$(GREEN)[OK]$(RESET) Clean complete"

## check-sdk: verify PICO_SDK_PATH is set and valid
check-sdk:
    @if [ ! -d "$(PICO_SDK)" ]; then \
        echo "$(RED)[ERR]$(RESET) Pico SDK not found at: $(PICO_SDK)"; \
        echo ""; \
        echo "  Install it:"; \
        echo "    git clone https://github.com/raspberrypi/pico-sdk \\"; \
        echo "      --recurse-submodules $(PICO_SDK)"; \
        echo ""; \
        echo "  Or set the path:"; \
        echo "    make build PICO_SDK=/path/to/pico-sdk"; \
        echo ""; \
        exit 1; \
    fi

## check-tools: verify required tools are installed
check-tools:
    @missing=""; \
    for tool in cmake arm-none-eabi-gcc arm-none-eabi-size; do \
        if ! command -v $$tool >/dev/null 2>&1; then \
            missing="$$missing $$tool"; \
        fi; \
    done; \
    if [ -n "$$missing" ]; then \
        echo "$(RED)[ERR]$(RESET) Missing tools:$$missing"; \
        echo ""; \
        echo "  macOS:  brew install cmake arm-none-eabi-gcc"; \
        echo "  Ubuntu: sudo apt install cmake gcc-arm-none-eabi"; \
        echo ""; \
        exit 1; \
    fi

## help: show this help
help:
    @echo ""
    @echo "$(BLUE)Basement Monitor — C / Pico SDK$(RESET)"
    @echo "Pico SDK: $(PICO_SDK)"
    @echo ""
    @grep -E '^##' Makefile | sed 's/## /  make /'
    @echo ""
    @echo "$(YELLOW)Overrides:$(RESET)"
    @echo "  make build PICO_SDK=/custom/path/pico-sdk"
    @echo "  make build JOBS=8"
    @echo "  make monitor PORT=/dev/ttyACM0"
    @echo ""

You'll probably end up having a complete workspace something along the lines of this:

bunker-monitor-c/Makefile
bunker-monitor-tinygo/Makefile
bunker-monitor-rust/Makefile

This could then be connected into a single Makefile that looks like:

# basement-monitor/Makefile  (root — calls into each subdirectory)

RED    := \033[0;31m
GREEN  := \033[0;32m
YELLOW := \033[0;33m
BLUE   := \033[0;34m
CYAN   := \033[0;36m
RESET  := \033[0m

DIRS := basement-monitor-c \
        basement-monitor-tinygo \
        basement-monitor-rust

.PHONY: all build clean run size fmt help \
       build-c build-tinygo build-rust \
       clean-c clean-tinygo clean-rust \
       size-c size-tinygo size-rust \
       fmt-c fmt-tinygo fmt-rust

all: build

## build: build all three implementations
build: build-c build-tinygo build-rust

build-c:
    @echo "$(CYAN)━━━ C / Pico SDK ━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
    @$(MAKE) -C basement-monitor-c build
    @echo ""

build-tinygo:
    @echo "$(CYAN)━━━ TinyGo ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
    @$(MAKE) -C basement-monitor-tinygo build
    @echo ""

build-rust:
    @echo "$(CYAN)━━━ Rust / Embassy ━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
    @$(MAKE) -C basement-monitor-rust build-release
    @echo ""

## clean: clean all three implementations
clean: clean-c clean-tinygo clean-rust

clean-c:
    @$(MAKE) -C basement-monitor-c clean

clean-tinygo:
    @$(MAKE) -C basement-monitor-tinygo clean

clean-rust:
    @$(MAKE) -C basement-monitor-rust clean

## size: compare binary sizes across all three
size: build
    @echo ""
    @echo "$(CYAN)━━━ Binary Size Comparison ━━━━━━━━━━━━━━━━$(RESET)"
    @echo ""
    @printf "  %-12s %s\n" "Language" "Size"
    @printf "  %-12s %s\n" "────────" "────"
    @C_SIZE=$$(ls -la basement-monitor-c/build/basement-monitor.uf2 \
        2>/dev/null | awk '{print $$5}'); \
    GO_SIZE=$$(ls -la basement-monitor-tinygo/basement-monitor.uf2 \
        2>/dev/null | awk '{print $$5}'); \
    RS_SIZE=$$(ls -la basement-monitor-rust/basement-monitor.uf2 \
        2>/dev/null | awk '{print $$5}'); \
    printf "  %-12s %s bytes\n" "C"       "$${C_SIZE:-n/a}"; \
    printf "  %-12s %s bytes\n" "TinyGo"  "$${GO_SIZE:-n/a}"; \
    printf "  %-12s %s bytes\n" "Rust"    "$${RS_SIZE:-n/a}"
    @echo ""

## fmt: format all three implementations
fmt: fmt-c fmt-tinygo fmt-rust

fmt-c:
    @$(MAKE) -C basement-monitor-c format

fmt-tinygo:
    @$(MAKE) -C basement-monitor-tinygo fmt

fmt-rust:
    @$(MAKE) -C basement-monitor-rust fmt

## run-c: flash C build to connected Pico W
run-c:
    @$(MAKE) -C basement-monitor-c run

## run-tinygo: flash TinyGo build to connected Pico W
run-tinygo:
    @$(MAKE) -C basement-monitor-tinygo run

## run-rust: flash Rust build to connected Pico W
run-rust:
    @$(MAKE) -C basement-monitor-rust run

## help: show this help
help:
    @echo ""
    @echo "$(CYAN)Basement Monitor — Triad Comparison$(RESET)"
    @echo "C  ·  TinyGo  ·  Rust/Embassy"
    @echo ""
    @grep -E '^##' Makefile | sed 's/## /  make /'
    @echo ""
    @echo "$(YELLOW)Per-implementation targets:$(RESET)"
    @echo "  make build-c       make build-tinygo    make build-rust"
    @echo "  make clean-c       make clean-tinygo    make clean-rust"
    @echo "  make run-c         make run-tinygo      make run-rust"
    @echo ""

Make Reference

Command              C                TinyGo           Rust
─────────────────────────────────────────────────────────────
make build           cmake + make     tinygo build     cargo build
make clean           rm -rf build/    rm *.uf2         cargo clean
make run             cp .uf2 + screen tinygo flash +   cargo flash +
                     /dev/tty*        tinygo monitor   cargo embed
make size            arm-none-        tinygo build     cargo bloat
                     eabi-size        -size=full       --crates
make fmt             clang-format     gofmt            cargo fmt
make flash           cp to RPI-RP2    tinygo flash     cargo flash
make monitor         screen           tinygo monitor   cargo embed
make help            grep ## self     grep ## self     grep ## self

So now that we know how to build onto our circuit, we should have the board itself assembled by now and we should be ready to begin loading the source code onto the board. At this point, is where this guide is exploring and that I am writing for you today.

C gives you the smallest binary, the most hardware control, and the most mature ecosystem — but it gives you no help when you make mistakes. Every memory safety bug, every forgotten free(), every unguarded g_state access is your problem at 2am when the basement is flooding. TinyGo gives you Go’s goroutine model and standard library idioms — the most readable code of the three — but layers a GC and a runtime between you and the hardware, and the ecosystem is still catching up on Pico W specifics. Rust gives you compile-time proof that your pins are used correctly, your buffers don’t overflow, and your state is always accessed under a lock — with zero runtime overhead and binary sizes comparable to C — but demands the most upfront investment in satisfying the compiler before you ever see an LED blink. The right choice depends on whether your priority is shipping fast (TinyGo), maximum control (C), or maximum confidence (Rust).

Hardware

Component	Role	Pin
Raspberry Pi Pico W	Microcontroller + WiFi	—
DHT22	Temperature & humidity	GPIO2
Capacitive water sensor	Flood detection	GPIO3
Relay module	Cut power on flood	GPIO4
PIR motion sensor	Intrusion detection	GPIO5
SSD1306 OLED (I2C)	Local display	GPIO6/7
Active buzzer	Local alarm	GPIO8
MQ-7 CO sensor	Carbon monoxide	GPIO26 (ADC)

Trinity Comparison of C → Rust → TinyGo

Dimension	C	TinyGo	Rust/Embassy
Concurrency model	Manual poll loop, no true concurrency	Real goroutines, cooperative scheduler	Async tasks, cooperative, interrupt-driven
DHT22 timing	Busy-wait, blocks CPU entirely	Busy-wait in goroutine, others run	PIO hardware offload, CPU completely free
State sharing	`volatile` + `critical_section`, convention only	`sync.Mutex`, convention only	`Mutex<T>`, compiler enforced
Memory safety (HTTP buffers)	`char[N]`, silent overflow = UB	`make([]byte,n)` + GC	`heapless::String`, overflow = compile error
HTTP server architecture	lwIP raw callbacks, 4 callback functions	`net.Listen` + goroutine/conn, idiomatic Go	`embassy-net` TcpSocket, linear async code
Cleanup / resource mgmt	Manual `free()`, easy to forget	`defer conn.Close()`, automatic	Drop trait, automatic, enforced
Pin safety (exclusive use)	Convention only	Convention only	Compile-time ownership proof
Binary size	Smallest ~50KB	Medium ~200–400KB	Small ~80–150KB
GC pauses	None (no GC)	Yes, brief on allocations	None (no GC)
WiFi connect	Blocks CPU (IRQs run)	Blocks goroutine (others run)	Fully async, yields executor
Standard library available	C stdlib subset (no OS calls)	Go stdlib subset (growing)	`core` only, `no_std`
Driver ecosystem	Mature, large C libs	`tinygo/x/drivers`, growing fast	`embedded-hal` crates, mature
Build system	CMake + Pico SDK	`go mod` + `tinygo flash`	`cargo` + `cargo-embed`
Flash command	OpenOCD or drag `.uf2`	`tinygo flash -target pico-w`	`cargo flash` or `cargo-embed`
Readable code (subjective)	Medium (callbacks)	Highest (goroutines)	High (async/await)
Production maturity	Proven, decades of embedded C	Growing, 2–3 years Pico W support	Growing fast, 2–3 years Pico W support

Sensors

Here we are going to build out three implements of the sensors. We'll start with Go, and then we'll present Rust and then end of C. C will produce the smallest binary and will have the most stability - frankly speaking - but studying and researching alternative languages like Go and Rust for the purposes of building basement or bunker monitor systems, this kind of technology will give you personal security awareness in a way that not only did you build the circuits themselves for, but you also built the code for them and go them to work for yourself as well.

Go Implementation of `sensors/dht22.go`

package sensors

import (
    "machine"
    "time"
)

// DHT22Task reads temperature and humidity every 2 seconds.
//
// The DHT22 single-wire protocol is the hardest sensor to implement
// correctly in TinyGo because it requires microsecond timing.
//
// Comparison:
//   Rust:   PIO state machine handles timing in hardware, CPU free
//   C:      Busy-wait loops, CPU blocked for ~5ms per read
//   TinyGo: Same busy-wait approach as C, but wrapped in a goroutine
//           so other goroutines can run between reads.
//           During the 5ms read itself, this goroutine holds the CPU
//           (no yield point inside the bit-bang loop).
//
// The tinygo.org/x/drivers package has a dht driver but implementing
// it manually here shows the protocol clearly for the write-up.

func DHT22Task(pin machine.Pin, update func(func(*SensorState))) {
    // Configure pin — will switch direction during protocol
    pin.Configure(machine.PinConfig{Mode: machine.PinInputPullup})

    // DHT22 needs 1 second after power-on before first read
    time.Sleep(1 * time.Second)

    for {
        temp, humidity, ok := readDHT22(pin)

        if ok {
            update(func(s *SensorState) {
                s.TemperatureC = temp
                s.HumidityPct  = humidity
            })
            println("[DHT22]", temp, "C", humidity, "% RH")

            if humidity > 85.0 {
                println("[WARN ] High humidity — check for moisture")
            }
        } else {
            println("[DHT22] Read failed")
        }

        // DHT22 minimum interval between reads is 2 seconds.
        // time.Sleep yields this goroutine — other goroutines run.
        // This is the key difference from C's polling approach:
        // we're not burning CPU, we're genuinely sleeping.
        time.Sleep(2 * time.Second)
    }
}

// readDHT22 implements the DHT22 single-wire protocol.
// Returns (temperature_c, humidity_pct, ok).
// Returns false on timing timeout or checksum failure.
func readDHT22(pin machine.Pin) (float32, float32, bool) {
    var data [5]uint8

    // ── Send start signal ──────────────────────────────────────────────
    // Pull LOW for 18ms to wake the sensor
    pin.Configure(machine.PinConfig{Mode: machine.PinOutput})
    pin.Low()
    time.Sleep(18 * time.Millisecond)
    pin.High()
    time.Sleep(30 * time.Microsecond)

    // ── Switch to input ────────────────────────────────────────────────
    pin.Configure(machine.PinConfig{Mode: machine.PinInputPullup})

    // Wait for sensor to pull LOW (~80µs) then HIGH (~80µs)
    if !waitForLevel(pin, false, 200) { return 0, 0, false }
    if !waitForLevel(pin, true,  200) { return 0, 0, false }
    if !waitForLevel(pin, false, 200) { return 0, 0, false }

    // ── Read 40 bits ───────────────────────────────────────────────────
    for i := 0; i < 40; i++ {
        // Each bit: LOW 50µs, then HIGH duration encodes the bit value
        if !waitForLevel(pin, true, 100) { return 0, 0, false }

        // Measure HIGH duration
        start := time.Now()
        if !waitForLevel(pin, false, 100) { return 0, 0, false }
        duration := time.Since(start)

        data[i/8] <<= 1
        // HIGH > 40µs means bit is 1, otherwise 0
        if duration > 40*time.Microsecond {
            data[i/8] |= 1
        }
    }

    // ── Checksum ───────────────────────────────────────────────────────
    checksum := data[0] + data[1] + data[2] + data[3]
    if checksum != data[4] {
        println("[DHT22] Checksum mismatch")
        return 0, 0, false
    }

    // ── Decode ─────────────────────────────────────────────────────────
    rawHum  := uint16(data[0])<<8 | uint16(data[1])
    rawTemp := uint16(data[2]&0x7F)<<8 | uint16(data[3])
    negative := data[2]&0x80 != 0

    humidity := float32(rawHum) / 10.0
    temp     := float32(rawTemp) / 10.0
    if negative {
        temp = -temp
    }

    return temp, humidity, true
}

// waitForLevel waits for pin to reach the given level.
// Returns false on timeout (count iterations, not real time —
// TinyGo's time.Now() has overhead inside tight loops).
func waitForLevel(pin machine.Pin, level bool, maxCount int) bool {
    for i := 0; i < maxCount; i++ {
        if pin.Get() == level {
            return true
        }
        // Brief pause — gives other goroutines a chance if scheduler
        // is cooperative, but in practice this loop is too tight to yield
        time.Sleep(1 * time.Microsecond)
    }
    return false
}

It's super messy. AI makes interfacing with it a lot more hallucinogenic for human operator programming the interface. Once you understand the bitwise shifts that you're doing on the actual microcontroller itself, it makes a little more sense, but to say that it is super messy, is an understatement. I believe uint16(data[2]&0x7F)<<8 | uint16(data[3]) and data[2]&0x80 != 0 are legitimate brobdingnagdiums implemented in literal use.

The water sensor on the other hand is much more on point.

package sensors

import (
    "machine"
    "time"
)

// WaterTask polls the capacitive water sensor every 500ms.
//
// When water is detected:
//   - Activates the relay (cuts power to basement appliances)
//   - Sets alarm_active in shared state
//   - Logs the event
//
// Relay is deactivated when sensor clears.
// Alarm must be manually acknowledged (same decision as C version).
//
// TinyGo advantage over C here: this genuinely runs concurrently
// with other sensor goroutines. In C, a 500ms sleep in this function
// would block the entire main loop. Here, time.Sleep yields the
// goroutine scheduler — the DHT22, PIR, and CO goroutines continue.

func WaterTask(
    sensePin machine.Pin,
    relayPin machine.Pin,
    update func(func(*SensorState)),
) {
    sensePin.Configure(machine.PinConfig{Mode: machine.PinInputPullup})
    relayPin.Configure(machine.PinConfig{Mode: machine.PinOutput})
    relayPin.Low() // relay off at startup

    var lastWet bool

    for {
        // LOW = water present (pull-up config, sensor pulls down when wet)
        wet := !sensePin.Get()

        if wet != lastWet {
            if wet {
                println("[WATER] WATER DETECTED — activating relay")
                relayPin.High() // trigger relay
                update(func(s *SensorState) {
                    s.WaterDetected = true
                    s.AlarmActive   = true
                })
            } else {
                println("[WATER] Cleared — deactivating relay")
                relayPin.Low()
                update(func(s *SensorState) {
                    s.WaterDetected = false
                    // AlarmActive intentionally NOT cleared —
                    // same decision as C and Rust versions.
                    // A human should acknowledge a flood event.
                })
            }
            lastWet = wet
        }

        time.Sleep(500 * time.Millisecond)
    }
}

The PIR sensor is used for motion detection and is built with the sensors/pir.go file.

package sensors

import (
    "machine"
    "time"
)

// PIRTask monitors the passive infrared motion sensor.
//
// PIR sensors output HIGH when motion is detected and hold that
// level for their configured hold time (typically 2-5 seconds).
//
// TinyGo vs Rust comparison for this specific task:
//
//   Rust/Embassy:
//     sensor.wait_for_high().await   // zero CPU, interrupt-driven
//     sensor.wait_for_low().await    // zero CPU, interrupt-driven
//
//   TinyGo:
//     No wait_for_high equivalent in machine package.
//     We poll with time.Sleep — yields scheduler between polls
//     but wakeup latency is the sleep interval, not interrupt latency.
//     For PIR this is fine — human motion detection doesn't need
//     sub-millisecond response time.
//
//   C:
//     gpio_get() in a polling loop every 100ms in the main loop.
//     Same latency as TinyGo but shares the main thread with everything else.

func PIRTask(pin machine.Pin, update func(func(*SensorState))) {
    pin.Configure(machine.PinConfig{Mode: machine.PinInputPulldown})

    var lastMotion bool

    for {
        motion := pin.Get() // HIGH = motion detected

        if motion != lastMotion {
            if motion {
                println("[PIR  ] Motion detected in basement")
            } else {
                println("[PIR  ] Motion cleared")
            }
            update(func(s *SensorState) {
                s.MotionDetected = motion
            })
            lastMotion = motion
        }

        // 100ms poll interval — adequate for human motion detection
        time.Sleep(100 * time.Millisecond)
    }
}

Next is the MQ-7 CO sensor that is going to handled by the sensor/co.go file:

package sensors

import (
    "machine"
    "time"
)

// COTask reads the MQ-7 CO sensor via ADC every 5 seconds.
//
// TinyGo ADC usage is significantly cleaner than C:
//
//   C:
//     adc_init();
//     adc_gpio_init(26);
//     adc_select_input(0);
//     uint16_t raw = adc_read();
//
//   TinyGo:
//     adc := machine.ADC{Pin: machine.GPIO26}
//     adc.Configure(machine.ADCConfig{})
//     raw := adc.Get()
//
//   Rust:
//     let mut adc = Adc::new(p.ADC, Irqs, AdcConfig::default());
//     let mut ch  = Channel::new_pin(p.PIN_26, Pull::None);
//     let raw     = adc.read(&mut ch).await.unwrap();
//
// All three are functionally identical. TinyGo's is most concise.
// Rust's is the only one where the compiler verifies PIN_26 isn't
// used anywhere else simultaneously.

// SensorState is defined in dht22.go but shared across this package
// Re-declaring here would be a compile error — Go enforces one
// definition per package, unlike C's header include guards.

func COTask(pin machine.Pin, update func(func(*SensorState))) {
    adc := machine.ADC{Pin: pin}
    adc.Configure(machine.ADCConfig{})

    for {
        // machine.ADC.Get() returns 0-65535 (normalized to uint16 range)
        // regardless of the hardware's actual bit depth.
        // TinyGo normalizes ADC readings — C and Rust give you raw bits.
        raw := adc.Get()

        // Convert normalized reading to voltage (0-3.3V)
        voltage := float32(raw) / 65535.0 * 3.3

        // Approximate CO ppm from voltage — needs calibration in production
        var ppm uint16
        if voltage > 0.4 {
            ppm = uint16((voltage - 0.4) * 200.0)
        }

        update(func(s *SensorState) {
            s.CoPpm = ppm
            if ppm > 150 {
                s.AlarmActive = true
            }
        })

        if ppm > 50 {
            println("[CO   ] Elevated:", ppm, "ppm")
        }
        if ppm > 150 {
            println("[ERROR] DANGEROUS CO:", ppm, "ppm — EVACUATE")
        }

        time.Sleep(5 * time.Second)
    }
}

The last of the TinyGo sensors package is the state.go file, which is going to contain the shared data between the different sensor implementation files where they are common due to the use of the Go runtime.

package sensors

// SensorState is the shared data structure passed between goroutines.
// Defined once here, used across all sensor files in this package.
//
// Comparison across the three implementations:
//
//   Rust:
//     pub static STATE: Mutex<CriticalSectionRawMutex, SensorState>
//     Compiler prevents access without locking.
//     Clone is explicit and deliberate.
//
//   C:
//     volatile SensorState g_state;
//     + manual critical_section_enter/exit
//     Nothing prevents unsynchronized access.
//     volatile only prevents compiler optimization, not race conditions.
//
//   TinyGo:
//     var state SensorState + sync.Mutex
//     The race detector (go test -race) would catch misuse,
//     but TinyGo does not support -race on embedded targets.
//     Convention enforced by UpdateState/GetState functions.
//     Closer to C in safety than Rust — but Go idiom encourages
//     the channel-based alternative shown below.

type SensorState struct {
    WaterDetected  bool
    TemperatureC   float32
    HumidityPct    float32
    MotionDetected bool
    CoPpm          uint16
    AlarmActive    bool
}

// ── Alternative: channel-based state (more idiomatic Go) ──────────────────
//
// Instead of a mutex-protected struct, pure Go would use channels:
//
//   type StateUpdate struct { Field string; Value interface{} }
//   updates := make(chan StateUpdate, 10)
//
//   // Writer:
//   updates <- StateUpdate{"WaterDetected", true}
//
//   // Reader (single goroutine owns state):
//   for u := range updates {
//       applyUpdate(&state, u)
//   }
//
// This is the CSP model — "don't communicate by sharing memory,
// share memory by communicating."
//
// We don't use this pattern here because:
//   1. TinyGo's channel buffer is limited — overflow panics on device
//   2. HTTP handler needs synchronous reads — channel model requires
//      a request/response channel pair, adding complexity
//   3. The mutex approach maps more directly to the C and Rust versions
//      for comparison purposes
//
// In a production TinyGo project the channel approach is often better.
// This is one area where TinyGo genuinely differs from C and Rust —
// it has idiomatic concurrency primitives that neither of the others have.

This basic struct will later be implemented. Rust will also implement a struct.

Rust Implementation of `sensors.rs`

use embassy_rp::gpio::{Input, Output, Level, Pull};
use embassy_rp::adc::{Adc, Channel, Config as AdcConfig};
use embassy_rp::peripherals::*;
use embassy_time::{Duration, Instant, Timer};
use defmt::*;

use crate::STATE;

// ── Water sensor task ──────────────────────────────────────────────────────
//
// The capacitive water sensor outputs HIGH when dry, LOW when wet.
// When water is detected we:
//   1. Update shared state
//   2. Activate the relay (cuts power to basement appliances)
//   3. Trigger the alarm
//
// This is the most safety-critical sensor in the system.

#[embassy_executor::task]
pub async fn water_task(
    sense_pin: PIN_3,   // signal from water sensor
    relay_pin: PIN_4,   // relay control output
) {
    let sensor = Input::new(sense_pin, Pull::Up);
    let mut relay = Output::new(relay_pin, Level::Low);

    let mut last_state = false;

    loop {
        // Read water sensor — LOW means water present (pull-up config)
        let water_now = sensor.get_level() == Level::Low;

        if water_now != last_state {
            // State changed — log it
            if water_now {
                warn!("WATER DETECTED — activating relay and alarm");
                relay.set_high(); // trigger relay
            } else {
                info!("Water cleared — deactivating relay");
                relay.set_low();
            }
            last_state = water_now;

            // Update shared state — .lock().await is the async Mutex acquire
            // This is the equivalent of mu.Lock() in Go, but it yields
            // instead of blocking an OS thread
            let mut state = STATE.lock().await;
            state.water_detected = water_now;
            state.alarm_active   = water_now;
        }

        // Poll every 500ms — fast enough for flooding, not so fast
        // that we're burning cycles on a stable sensor
        Timer::after(Duration::from_millis(500)).await;
    }
}

// ── DHT22 temperature & humidity task ─────────────────────────────────────

#[embassy_executor::task]
pub async fn dht22_task(pin: PIN_2) {
    // DHT22 uses a single-wire protocol with very tight timing.
    // We need to drive the pin as output to send the start signal,
    // then switch to input to read the response.
    // Embassy's flexible-io support handles this cleanly.

    loop {
        // DHT22 needs at least 2 seconds between reads
        Timer::after(Duration::from_secs(2)).await;

        // Reading DHT22 requires precise microsecond timing.
        // In a real implementation you'd use embassy-rp's PIO state machine
        // to handle the bit-banging in hardware, freeing the CPU.
        // For clarity here we show the logic flow:

        match read_dht22().await {
            Ok((temp, humidity)) => {
                let mut state = STATE.lock().await;
                state.temperature_c = temp;
                state.humidity_pct  = humidity;
                info!("DHT22: {:.1}°C  {:.1}% RH", temp, humidity);

                // High humidity in a basement is a leading indicator
                // of water intrusion — worth logging even before the
                // water sensor triggers
                if humidity > 85.0 {
                    warn!("High humidity: {:.1}% — check for moisture", humidity);
                }
            }
            Err(e) => {
                warn!("DHT22 read failed: {}", e);
            }
        }
    }
}

async fn read_dht22() -> Result<(f32, f32), &'static str> {
    // Real implementation uses PIO or careful timing loops.
    // Returns (temperature_celsius, humidity_percent)
    Ok((21.5, 62.0)) // placeholder
}

// ── PIR motion sensor task ─────────────────────────────────────────────────

#[embassy_executor::task]
pub async fn pir_task(pin: PIN_5) {
    let sensor = Input::new(pin, Pull::Down);

    loop {
        // wait_for_high() suspends this task until the pin goes HIGH.
        // Zero CPU usage while waiting — Embassy wakes it via interrupt.
        // This is the embedded equivalent of blocking on a channel receive.
        sensor.wait_for_high().await;

        {
            let mut state = STATE.lock().await;
            state.motion_detected = true;
            info!("Motion detected in basement");
        }

        // Debounce — PIR sensors have a hold time of ~2s
        Timer::after(Duration::from_secs(2)).await;

        sensor.wait_for_low().await;

        {
            let mut state = STATE.lock().await;
            state.motion_detected = false;
        }
    }
}

// ── MQ-7 CO sensor task ────────────────────────────────────────────────────

#[embassy_executor::task]
pub async fn co_task(adc_peripheral: ADC, pin: PIN_26) {
    let mut adc = Adc::new(adc_peripheral, crate::Irqs, AdcConfig::default());
    let mut channel = Channel::new_pin(pin, Pull::None);

    loop {
        // ADC reads 0-4095 (12-bit) representing 0-3.3V
        // MQ-7 voltage output maps to CO concentration in ppm
        // Actual calibration requires a known CO source — this is approximate
        let raw = adc.read(&mut channel).await.unwrap_or(0);
        let voltage = (raw as f32 / 4095.0) * 3.3;

        // Rough CO ppm calculation — real deployment needs calibration curve
        let ppm = if voltage < 0.4 { 0u16 } else {
            ((voltage - 0.4) * 200.0) as u16
        };

        {
            let mut state = STATE.lock().await;
            state.co_ppm = ppm;
        }

        if ppm > 50 {
            warn!("CO level elevated: {} ppm", ppm);
        }
        if ppm > 150 {
            // DANGER threshold — activate alarm regardless of water state
            let mut state = STATE.lock().await;
            state.alarm_active = true;
            error!("DANGEROUS CO LEVEL: {} ppm — EVACUATE", ppm);
        }

        Timer::after(Duration::from_secs(5)).await;
    }
}

C Implementation of `sensors.c`

src/sensors.h

#ifndef SENSORS_H
#define SENSORS_H

#include <stdint.h>
#include <stdbool.h>
#include "pico/stdlib.h"
#include "hardware/adc.h"

// ── Pin assignments ────────────────────────────────────────────────────────
// Keeping all pin definitions in one header means a wiring change
// only touches one file — same discipline as Rust's peripheral ownership
// but enforced by convention, not the compiler

#define PIN_DHT22       2   // single-wire data
#define PIN_WATER_SENSE 3   // capacitive water sensor signal
#define PIN_RELAY       4   // relay module IN
#define PIN_PIR         5   // PIR motion sensor OUT
#define PIN_OLED_SDA    6   // I2C data
#define PIN_OLED_SCL    7   // I2C clock
#define PIN_BUZZER      8   // active buzzer
#define PIN_CO_ANALOG   26  // MQ-7 analog out → ADC0

// ── Shared state ───────────────────────────────────────────────────────────
// In C there is no Mutex<SensorState> enforced by a compiler.
// We use a volatile struct + critical sections manually.
// volatile tells the compiler "don't optimize reads away —
// another context may have changed this value"
// This is what Rust's Mutex + borrow checker replaces.

typedef struct {
    volatile bool     water_detected;
    volatile float    temperature_c;
    volatile float    humidity_pct;
    volatile bool     motion_detected;
    volatile uint16_t co_ppm;
    volatile bool     alarm_active;
} SensorState;

// Global state — in Rust this would be static Mutex<SensorState>
// In C it is just a global with a manual critical section guard
extern SensorState g_state;

// ── Function declarations ──────────────────────────────────────────────────

// DHT22 returns false on checksum or timing failure
// In Rust this would be Result<(f32,f32), DhtError>
// In C we return bool and write into out pointers
bool     dht22_read(uint8_t pin, float *temp_c, float *humidity_pct);

void     water_sensor_init(void);
bool     water_sensor_read(void);    // true = water present

void     pir_sensor_init(void);
bool     pir_sensor_read(void);      // true = motion detected

void     co_sensor_init(void);
uint16_t co_sensor_read_ppm(void);

// Critical section helpers — manually what Rust does automatically
// with MutexGuard drop semantics
void     state_lock(void);
void     state_unlock(void);

#endif // SENSORS_H

src/sensors.c

#include "sensors.h"
#include "pico/stdlib.h"
#include "pico/critical_section.h"
#include "hardware/adc.h"
#include "hardware/gpio.h"
#include <stdio.h>
#include <string.h>

// ── Global state + lock ────────────────────────────────────────────────────
// This is the C equivalent of:
//   pub static STATE: Mutex<CriticalSectionRawMutex, SensorState>
// The difference: Rust prevents you from accessing STATE without locking.
// C has no such guarantee — nothing stops a bug from reading g_state
// directly without calling state_lock() first. Convention only.

SensorState g_state = {
    .water_detected  = false,
    .temperature_c   = 0.0f,
    .humidity_pct    = 0.0f,
    .motion_detected = false,
    .co_ppm          = 0,
    .alarm_active    = false,
};

static critical_section_t g_state_cs;
static bool g_cs_initialized = false;

void state_lock(void) {
    if (!g_cs_initialized) {
        critical_section_init(&g_state_cs);
        g_cs_initialized = true;
    }
    critical_section_enter_blocking(&g_state_cs);
}

void state_unlock(void) {
    critical_section_exit(&g_state_cs);
}

// ── DHT22 ─────────────────────────────────────────────────────────────────
//
// The DHT22 single-wire protocol requires microsecond timing.
// In Rust/Embassy this would be done with PIO hardware offload.
// In C with the Pico SDK we bit-bang using busy-wait loops.
// This is simpler to read but blocks the CPU during the ~5ms read cycle.
// Compare to Rust: read_dht22().await yields the executor during the wait.
// In C: the CPU spins doing nothing while we wait for edges.
//
// Protocol timing:
//   Host pulls LOW  18ms  → start signal
//   Host releases   → sensor pulls LOW 80µs then HIGH 80µs → ready
//   40 bits follow  → each bit: LOW 50µs, then HIGH 26µs=0 or 70µs=1
//   Final: 8b humidity int, 8b humidity dec, 8b temp int, 8b temp dec, 8b checksum

#define DHT22_START_LOW_MS   18
#define DHT22_TIMEOUT_US     1000

static bool wait_for_level(uint8_t pin, bool level, uint32_t timeout_us) {
    uint32_t start = time_us_32();
    while (gpio_get(pin) != level) {
        if (time_us_32() - start > timeout_us) {
            return false;  // timeout
        }
    }
    return true;
}

bool dht22_read(uint8_t pin, float *temp_c, float *humidity_pct) {
    uint8_t data[5] = {0};

    // ── Send start signal ──────────────────────────────────────────────
    gpio_set_dir(pin, GPIO_OUT);
    gpio_put(pin, 0);               // pull LOW
    sleep_ms(DHT22_START_LOW_MS);   // hold 18ms — blocks CPU entirely
    gpio_put(pin, 1);               // release
    sleep_us(30);

    // ── Switch to input, wait for sensor response ──────────────────────
    gpio_set_dir(pin, GPIO_IN);
    gpio_pull_up(pin);

    if (!wait_for_level(pin, false, DHT22_TIMEOUT_US)) return false; // LOW 80µs
    if (!wait_for_level(pin, true,  DHT22_TIMEOUT_US)) return false; // HIGH 80µs
    if (!wait_for_level(pin, false, DHT22_TIMEOUT_US)) return false; // start of data

    // ── Read 40 bits ───────────────────────────────────────────────────
    for (int i = 0; i < 40; i++) {
        // Each bit starts with a 50µs LOW pulse
        if (!wait_for_level(pin, true, DHT22_TIMEOUT_US)) return false;

        // Measure how long HIGH lasts:
        // ~26µs = 0, ~70µs = 1
        uint32_t high_start = time_us_32();
        if (!wait_for_level(pin, false, DHT22_TIMEOUT_US)) return false;
        uint32_t high_duration = time_us_32() - high_start;

        data[i / 8] <<= 1;
        if (high_duration > 40) {
            data[i / 8] |= 1;  // it's a 1
        }
        // if <= 40µs it's a 0, the bit is already 0 from the shift
    }

    // ── Verify checksum ────────────────────────────────────────────────
    // checksum = sum of first 4 bytes, lower 8 bits
    uint8_t checksum = data[0] + data[1] + data[2] + data[3];
    if (checksum != data[4]) {
        printf("[DHT22] checksum failed: got %02x expected %02x\n",
               checksum, data[4]);
        return false;
    }

    // ── Decode ─────────────────────────────────────────────────────────
    // Humidity: bytes 0-1, value in tenths of percent
    uint16_t raw_hum  = ((uint16_t)data[0] << 8) | data[1];
    // Temperature: bytes 2-3, bit15 = sign, value in tenths of degree
    uint16_t raw_temp = ((uint16_t)(data[2] & 0x7F) << 8) | data[3];
    bool negative = (data[2] & 0x80) != 0;

    *humidity_pct = raw_hum  / 10.0f;
    *temp_c       = raw_temp / 10.0f * (negative ? -1.0f : 1.0f);

    return true;
}

// ── Water sensor ───────────────────────────────────────────────────────────

void water_sensor_init(void) {
    gpio_init(PIN_WATER_SENSE);
    gpio_set_dir(PIN_WATER_SENSE, GPIO_IN);
    gpio_pull_up(PIN_WATER_SENSE);  // HIGH = dry, LOW = water

    gpio_init(PIN_RELAY);
    gpio_set_dir(PIN_RELAY, GPIO_OUT);
    gpio_put(PIN_RELAY, 0);         // relay off at startup
}

bool water_sensor_read(void) {
    // LOW = water present (capacitive sensor pulls down when wet)
    return !gpio_get(PIN_WATER_SENSE);
}

// ── PIR motion sensor ──────────────────────────────────────────────────────

void pir_sensor_init(void) {
    gpio_init(PIN_PIR);
    gpio_set_dir(PIN_PIR, GPIO_IN);
    gpio_pull_down(PIN_PIR);  // PIR output is active HIGH
}

bool pir_sensor_read(void) {
    return gpio_get(PIN_PIR);
}

// ── MQ-7 CO sensor ────────────────────────────────────────────────────────
//
// MQ-7 needs a heating cycle: 60s at 5V, 90s at 1.4V.
// For simplicity in this implementation we just read the analog output.
// A production version would implement the heating cycle via PWM on a
// separate voltage control pin.

void co_sensor_init(void) {
    // ADC init — PIN_26 is ADC0 on the Pico
    adc_init();
    adc_gpio_init(PIN_CO_ANALOG);
    adc_select_input(0);  // ADC channel 0 = GPIO26
}

uint16_t co_sensor_read_ppm(void) {
    adc_select_input(0);
    uint16_t raw = adc_read();  // 0-4095 (12-bit)

    // Convert ADC reading to voltage
    float voltage = (raw / 4095.0f) * 3.3f;

    // Approximate CO ppm from voltage
    // Real calibration needs a known CO concentration reference
    if (voltage < 0.4f) return 0;
    return (uint16_t)((voltage - 0.4f) * 200.0f);
}

src/sensors_loop.c

#include "sensors.h"
#include "pico/stdlib.h"
#include <stdio.h>

// These are called from the main loop on their own timing cadence.
// In Rust/Embassy each of these would be a separate async task running
// concurrently. In C without an RTOS they share one execution thread
// and we manually track when each one is "due" to run next.
//
// This is the fundamental structural difference:
//   Rust: 6 async tasks, Embassy schedules them cooperatively
//   C:    1 loop, you manually schedule everything via timestamps

static uint32_t next_dht22_ms    = 0;
static uint32_t next_water_ms    = 0;
static uint32_t next_pir_ms      = 0;
static uint32_t next_co_ms       = 0;

void sensors_poll_all(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    // ── DHT22 every 2000ms ─────────────────────────────────────────────
    if (now >= next_dht22_ms) {
        next_dht22_ms = now + 2000;

        float temp = 0.0f, hum = 0.0f;
        if (dht22_read(PIN_DHT22, &temp, &hum)) {
            state_lock();
            g_state.temperature_c = temp;
            g_state.humidity_pct  = hum;
            state_unlock();

            printf("[DHT22] %.1f°C  %.1f%% RH\n", temp, hum);

            if (hum > 85.0f) {
                printf("[WARN ] High humidity: %.1f%% — check for moisture\n", hum);
            }
        } else {
            printf("[DHT22] Read failed\n");
        }
    }

    // ── Water sensor every 500ms ───────────────────────────────────────
    if (now >= next_water_ms) {
        next_water_ms = now + 500;

        bool wet = water_sensor_read();

        state_lock();
        bool was_wet = g_state.water_detected;
        g_state.water_detected = wet;
        if (wet && !was_wet) {
            // Transition: dry → wet
            g_state.alarm_active = true;
            gpio_put(PIN_RELAY, 1);  // activate relay
            printf("[WATER] WATER DETECTED — relay ON, alarm active\n");
        } else if (!wet && was_wet) {
            // Transition: wet → dry
            // Note: we do NOT auto-clear alarm_active here.
            // A human should acknowledge a flood event.
            gpio_put(PIN_RELAY, 0);
            printf("[WATER] Cleared — relay OFF\n");
        }
        state_unlock();
    }

    // ── PIR every 100ms ────────────────────────────────────────────────
    if (now >= next_pir_ms) {
        next_pir_ms = now + 100;

        bool motion = pir_sensor_read();
        state_lock();
        bool was_motion = g_state.motion_detected;
        g_state.motion_detected = motion;
        state_unlock();

        if (motion && !was_motion) {
            printf("[PIR  ] Motion detected\n");
        }
    }

    // ── CO sensor every 5000ms ─────────────────────────────────────────
    if (now >= next_co_ms) {
        next_co_ms = now + 5000;

        uint16_t ppm = co_sensor_read_ppm();
        state_lock();
        g_state.co_ppm = ppm;
        if (ppm > 150) {
            g_state.alarm_active = true;
        }
        state_unlock();

        if (ppm > 50) {
            printf("[CO   ] Elevated: %u ppm\n", ppm);
        }
        if (ppm > 150) {
            printf("[ERROR] DANGEROUS CO: %u ppm — EVACUATE\n", ppm);
        }
    }
}

In C with no RTOS, the “task” concept doesn’t exist natively. We implement a cooperative loop scheduler in main.

Verdict of the Trinity

Rust for expression followed by C for stability. TinyGo is a joke, but technically possible!

Main Package

Now we have a sensors package built and the C and Rust projects have their respective sensor file, let's implement the main.go, main.c and main.rs files.

`main.go` Implementation

package main

import (
    "basement-monitor/alarm"
    "basement-monitor/display"
    "basement-monitor/http"
    "basement-monitor/sensors"
    "basement-monitor/wifi"
    "machine"
    "sync"
    "time"
)

// ── Shared state ───────────────────────────────────────────────────────────
//
// TinyGo supports sync.Mutex — but it is NOT the same as Go's runtime mutex.
// Under the hood TinyGo's mutex disables interrupts on Cortex-M rather than
// parking a goroutine. This means:
//   - Lock() is fast but briefly disables ALL interrupts
//   - You must never hold the lock while doing I2C/SPI/UART operations
//   - Contrast with Rust: Mutex<T> in Embassy uses critical sections too
//     but the compiler enforces you don't hold it across .await points
//   - Contrast with C: critical_section_enter_blocking() is the same
//     mechanism but nothing enforces usage discipline
//
// TinyGo goroutines are real but limited:
//   - Cooperative, not preemptive on single-core RP2040
//   - Stack size is fixed at compile time (default 1KB per goroutine)
//   - No goroutine leak detection
//   - channel operations are the primary synchronization primitive
//   - sync.WaitGroup works but blocks the scheduler

type SensorState struct {
    WaterDetected  bool
    TemperatureC   float32
    HumidityPct    float32
    MotionDetected bool
    CoPpm          uint16
    AlarmActive    bool
}

var (
    stateMu sync.Mutex
    state   SensorState
)

// GetState returns a snapshot of current sensor state.
// Pattern identical to Rust's STATE.lock().await + clone()
// and Go server's room.Snapshot — point-in-time copy.
func GetState() SensorState {
    stateMu.Lock()
    s := state // copy
    stateMu.Unlock()
    return s
}

// UpdateState applies a mutation function under the lock.
// This is cleaner than exposing the mutex directly —
// callers can't forget to unlock.
func UpdateState(fn func(*SensorState)) {
    stateMu.Lock()
    fn(&state)
    stateMu.Unlock()
}

func main() {
    // Small startup delay — lets USB serial connect before logging
    time.Sleep(2 * time.Second)

    println("[MAIN ] Basement monitor starting (TinyGo)")
    println("[MAIN ] Target: Raspberry Pi Pico W")

    // ── Pin configuration ──────────────────────────────────────────────
    // In TinyGo, machine.GPIO* constants map directly to RP2040 GPIO numbers.
    // This is equivalent to:
    //   Rust:  Output::new(p.PIN_2, Level::Low)
    //   C:     gpio_init(2); gpio_set_dir(2, GPIO_OUT);
    // TinyGo's machine package abstracts the register writes but unlike
    // Rust, two goroutines CAN both configure the same pin — no ownership
    // enforcement at compile time.

    dht22Pin  := machine.GPIO2
    waterPin  := machine.GPIO3
    relayPin  := machine.GPIO4
    pirPin    := machine.GPIO5
    sdaPin    := machine.GPIO6
    sclPin    := machine.GPIO7
    buzzerPin := machine.GPIO8
    coPin     := machine.GPIO26  // ADC0

    // ── Goroutine-based task model ─────────────────────────────────────
    //
    // This is TinyGo's closest equivalent to Embassy's task spawning.
    // Syntactically identical to standard Go.
    // Under the hood: TinyGo's scheduler is a simple cooperative
    // round-robin — goroutines yield at channel ops and time.Sleep.
    //
    // Compare:
    //   Rust:   spawner.spawn(sensors::dht22_task(p.PIN_2)).unwrap()
    //   TinyGo: go sensors.DHT22Task(dht22Pin, UpdateState)
    //   C:      no equivalent — polling loop only
    //
    // The TinyGo version looks most like standard Go and is the most
    // readable of the three — but has the least runtime safety guarantees.

    go sensors.DHT22Task(dht22Pin, UpdateState)
    go sensors.WaterTask(waterPin, relayPin, UpdateState)
    go sensors.PIRTask(pirPin, UpdateState)
    go sensors.COTask(coPin, UpdateState)
    go display.OLEDTask(sdaPin, sclPin, GetState)
    go alarm.AlarmTask(buzzerPin, GetState)

    // WiFi runs synchronously before HTTP server starts —
    // same constraint as C. TinyGo's WiFi drivers for Pico W
    // do not yet support a fully async connection flow.
    // The goroutine blocks here until connected or timeout.
    //
    // In Rust: wifi.join().await yields Embassy's executor
    // In C:    blocks the CPU entirely
    // In TinyGo: blocks this goroutine, others can still run
    //            IF there are yield points in the WiFi driver.
    //            In practice the CYW43 driver does yield internally.

    ip, err := wifi.Connect("YourNetworkName", "YourPassword")
    if err != nil {
        println("[MAIN ] WiFi failed:", err.Error())
        println("[MAIN ] Running in offline mode")
    } else {
        println("[MAIN ] Connected — IP:", ip)
        go http.ServeTask(GetState)
    }

    // main goroutine idles.
    // Unlike C's while(true) polling loop, we genuinely have nothing
    // to do here — the goroutines above handle everything.
    // select{} blocks forever without spinning the CPU.
    //
    // This is the most elegant version of this pattern across the three:
    //   Rust: loop { Timer::after(secs(60)).await; }
    //   C:    while(true) { poll_all(); sleep_us(100); }
    //   TinyGo: select {}   ← clean, zero CPU, zero boilerplate
    select {}
}

When building with TinyGo you'll need these flash commands:

# Install TinyGo first: https://tinygo.org/getting-started/install/

# Build and flash to Pico W
tinygo flash \
    -target=pico-w \
    -opt=z \
    .

# Build only (produces .uf2)
tinygo build \
    -target=pico-w \
    -opt=z \
    -o basement-monitor.uf2 \
    .

# Monitor serial output
tinygo monitor -target=pico-w

# Check binary size — flash is limited to 2MB on Pico W
tinygo build -target=pico-w -size=full .

`main.c` Implementation

#include <stdio.h>
#include <string.h>
#include "pico/stdlib.h"
#include "pico/cyw43_arch.h"

#include "sensors.h"
#include "display.h"
#include "alarm.h"
#include "wifi.h"
#include "http.h"

// ── Entry point ────────────────────────────────────────────────────────────
//
// The fundamental architectural difference from Rust is visible here.
//
// Rust/Embassy:
//   main() spawns 6 async tasks and returns.
//   Embassy's executor drives all 6 tasks concurrently on one or both cores.
//   Each task has its own stack, runs independently, yields at .await points.
//   The compiler guarantees no data races via the borrow checker.
//
// C (no RTOS):
//   main() runs one infinite loop.
//   Every "task" is a poll function that checks a timestamp and
//   returns immediately if it's not time to run yet.
//   One thing runs at a time. Nothing is truly concurrent.
//   The programmer is responsible for never blocking in a poll function.
//   The compiler offers no help if you forget state_lock() before g_state access.
//
// Both approaches work. The C version is simpler to understand mechanically.
// The Rust version scales better and fails earlier (at compile time).

int main(void) {
    // Initialize Pico SDK stdio — routes printf to USB serial
    stdio_init_all();

    // Small delay so USB serial has time to connect before we start logging
    sleep_ms(2000);
    printf("\n[MAIN ] Basement monitor starting\n");

    // ── Hardware initialization ────────────────────────────────────────
    water_sensor_init();
    pir_sensor_init();
    co_sensor_init();
    display_init();
    alarm_init();

    // ── Network initialization ─────────────────────────────────────────
    // wifi_init() blocks until connected or timeout.
    // In Rust: wifi.join().await — yields the executor during connection.
    // In C:    blocks the CPU. Nothing else runs for up to 30 seconds.
    //          lwIP background IRQ still processes packets during this time
    //          but our sensor polling loop is completely paused.
    if (!wifi_init()) {
        printf("[MAIN ] WiFi failed — running in offline mode\n");
        // Continue without network — sensors and alarm still work
    } else {
        http_server_init();
    }

    printf("[MAIN ] Entering main loop\n");

    // ── Main loop ──────────────────────────────────────────────────────
    // This is the scheduler. Each poll_*() function:
    //   1. Checks if it's time to run
    //   2. Does its work if yes, returns immediately if no
    //   3. MUST NOT block — blocking here stalls all other functions
    //
    // The loop runs as fast as possible — typically thousands of times
    // per second. Each poll function uses timestamps to self-throttle.
    //
    // In Rust/Embassy this loop doesn't exist. Each task IS its own loop,
    // sleeping at Timer::after().await without consuming CPU.
    while (true) {
        sensors_poll_all();   // DHT22, water, PIR, CO
        alarm_poll();         // buzzer pulsing
        display_poll();       // OLED refresh
        http_server_poll();   // lwIP processing (no-op in background mode)

        // Yield to lwIP background processing.
        // In threadsafe_background mode this is technically not needed
        // but it is good practice and costs almost nothing.
        cyw43_arch_poll();

        // Very brief sleep — gives IRQs a chance to fire.
        // Without this, tight loops on Cortex-M can starve interrupt handlers.
        // In Rust/Embassy: .await points are where IRQs are naturally serviced.
        sleep_us(100);
    }

    // Unreachable — microcontrollers never exit main()
    return 0;
}

`main.rs` Implementation

#![no_std]      // no standard library — we're on bare metal
#![no_main]     // no standard main() — Embassy provides the entry point

use embassy_executor::Spawner;
use embassy_rp::gpio::{Input, Level, Output, Pull};
use embassy_rp::peripherals::*;
use embassy_rp::{bind_interrupts, i2c, pio, spi};
use embassy_time::{Duration, Timer};
use static_cell::StaticCell;
use defmt::*;
use {defmt_rtt as _, panic_probe as _};

// Pull in our modules
mod sensors;
mod display;
mod alarm;
mod wifi;
mod http;

// Shared state between tasks — Embassy's Mutex is async-aware
// This is the equivalent of your room.Snapshot — a point-in-time
// view of the system that any task can read
use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::mutex::Mutex;

// SensorState is shared across ALL tasks via this static Mutex.
// No Arc needed — static lifetime covers the whole program.
// CriticalSectionRawMutex is safe across interrupt contexts.
pub static STATE: Mutex<CriticalSectionRawMutex, SensorState> =
    Mutex::new(SensorState::new());

#[derive(Clone)]
pub struct SensorState {
    pub water_detected: bool,
    pub temperature_c:  f32,
    pub humidity_pct:   f32,
    pub motion_detected: bool,
    pub co_ppm:         u16,
    pub alarm_active:   bool,
}

impl SensorState {
    pub const fn new() -> Self {
        Self {
            water_detected:  false,
            temperature_c:   0.0,
            humidity_pct:    0.0,
            motion_detected: false,
            co_ppm:          0,
            alarm_active:    false,
        }
    }
}

// bind_interrupts wires the RP2040's hardware interrupt vectors
// to Embassy's async drivers — this is what lets .await work on I2C, SPI etc.
bind_interrupts!(struct Irqs {
    I2C0_IRQ  => i2c::InterruptHandler<I2C0>;
    PIO0_IRQ_0 => pio::InterruptHandler<PIO0>;
    USBCTRL_IRQ => embassy_rp::usb::InterruptHandler<USB>;
});

// Embassy's entry point macro — replaces main()
// Spawner lets us launch async tasks, equivalent to `go func()`
#[embassy_executor::main]
async fn main(spawner: Spawner) {
    // Take ownership of ALL peripherals at startup.
    // This is Rust enforcing that nothing can double-use a pin —
    // at compile time, not runtime.
    let p = embassy_rp::init(Default::default());

    info!("Basement monitor starting up");

    // ── WiFi init (Pico W specific) ────────────────────────────────────
    let wifi_state = wifi::init(
        spawner,
        p.PIN_23, p.PIN_24, p.PIN_25, p.PIN_29,
        p.PIO0, p.DMA_CH0,
        Irqs,
    ).await;

    // ── Spawn independent async tasks ─────────────────────────────────
    // Each of these is like a goroutine — cooperative, cheap, no OS thread.
    // Embassy schedules them on a single core (or both cores on RP2040).

    // Reads DHT22 every 2s, updates STATE
    spawner.spawn(sensors::dht22_task(p.PIN_2)).unwrap();

    // Reads water sensor every 500ms, triggers alarm if wet
    spawner.spawn(sensors::water_task(p.PIN_3, p.PIN_4)).unwrap();

    // Reads PIR motion sensor
    spawner.spawn(sensors::pir_task(p.PIN_5)).unwrap();

    // Reads MQ-7 CO sensor via ADC
    spawner.spawn(sensors::co_task(p.ADC, p.PIN_26)).unwrap();

    // Drives SSD1306 OLED over I2C, refreshes every second
    spawner.spawn(display::oled_task(p.I2C0, p.PIN_6, p.PIN_7, Irqs)).unwrap();

    // Manages buzzer and relay based on STATE.alarm_active
    spawner.spawn(alarm::alarm_task(p.PIN_8, p.PIN_9)).unwrap();

    // HTTP server — serves sensor JSON and triggers
    spawner.spawn(http::server_task(wifi_state)).unwrap();

    // main task just idles — all real work is in the spawned tasks
    loop {
        Timer::after(Duration::from_secs(60)).await;
    }
}

Next we need to build out the display/oled.go, display.rs and the display.h | display.c implementations to get a visual representation of the bunker or basement monitor.

`display/oled.go` Implementation

// display/oled.go
//
// SSD1306 128x64 OLED display driver over I2C.
// Implements the same two-page rotating UI as display.rs and display.c:
//
//   Page 0 (Sensors): water, temp, humidity, alarm
//   Page 1 (Status):  motion, CO bar graph, network IP
//
// Architecture comparison for this file specifically:
//
//   Rust:   embedded-graphics crate — Point, Rectangle, Text primitives.
//           heapless::String — zero-allocation formatting.
//           ssd1306 crate manages framebuffer + flush.
//           Compiler owns I2C peripheral exclusively via type system.
//
//   C:      Hand-rolled framebuffer, font table, and primitives from scratch.
//           snprintf into stack buffers — zero heap allocation.
//           Nothing prevents two functions accessing I2C simultaneously.
//
//   TinyGo: tinygo/x/drivers/ssd1306 manages framebuffer + flush.
//           tinyfont package for glyph rendering — same role as
//           embedded-graphics MonoTextStyle in Rust.
//           fmt.Sprintf allocates — triggers GC on each call.
//           Goroutine owns display — scheduler enforces single access
//           by convention (not compiler enforcement like Rust).

package display

import (
    "basement-monitor/sensors"
    "fmt"
    "machine"
    "time"

    "tinygo.org/x/drivers/ssd1306"
    "tinygo.org/x/tinyfont"
    "tinygo.org/x/tinyfont/freemono"
    "tinygo.org/x/tinyfont/gophers"
)

// ── Layout constants ───────────────────────────────────────────────────────
// Mirror the constants in display.h and display.rs exactly so the
// write-up comparison is apples-to-apples.

const (
    screenW = 128
    screenH = 64

    // Row Y positions in pixels — matches ROW_0..ROW_7 in display.h
    // and ROW_0..ROW_5 in display.rs
    row0 = 0
    row1 = 8
    row2 = 16
    row3 = 24
    row4 = 32
    row5 = 40
    row6 = 48
    row7 = 56

    // Page rotation: switch every 50 × 100ms ticks = 5 seconds
    pageTicks = 50

    // I2C
    oledAddr = 0x3C
    i2cFreq  = 400 * machine.KHz
)

// ── Display pages ──────────────────────────────────────────────────────────
// Identical enum to DisplayPage in display.h and Page in display.rs.

type page uint8

const (
    pageSensors page = 0
    pageStatus  page = 1
    pageCount        = 2
)

func (p page) next() page {
    if p == pageSensors {
        return pageStatus
    }
    return pageSensors
}

// ── Color constants ────────────────────────────────────────────────────────
// SSD1306 is monochrome. The driver uses these to set or clear pixels.

const (
    colorOn  = ssd1306.White
    colorOff = ssd1306.Black
)

// ── OLEDTask ───────────────────────────────────────────────────────────────

// OLEDTask initializes the SSD1306 and runs the display refresh loop.
// Identical entry point signature to oled_task() in display.rs.
//
// In Rust:   #[embassy_executor::task] — compiler registers it as a task
// In C:      display_init() + display_poll() called from main loop
// In TinyGo: go display.OLEDTask(...) from main.go — goroutine

func OLEDTask(
    sdaPin    machine.Pin,
    sclPin    machine.Pin,
    getState  func() sensors.SensorState,
) {
    // ── Initialize I2C ─────────────────────────────────────────────────
    // TinyGo's machine.I2C0.Configure is the equivalent of:
    //   Rust:  I2c::new_async(i2c_peripheral, scl, sda, irqs, config)
    //   C:     i2c_init() + gpio_set_function() + gpio_pull_up()
    err := machine.I2C0.Configure(machine.I2CConfig{
        Frequency: i2cFreq,
        SDA:       sdaPin,
        SCL:       sclPin,
    })
    if err != nil {
        println("[OLED ] I2C configure failed:", err.Error())
        return
    }

    // ── Initialize SSD1306 ─────────────────────────────────────────────
    // tinygo/x/drivers/ssd1306 manages the framebuffer internally —
    // same role as Rust's ssd1306 crate in BufferedGraphicsMode.
    // C manages the framebuffer manually as g_framebuffer[8][128].
    display := ssd1306.NewI2C(machine.I2C0)
    display.Configure(ssd1306.Config{
        Address: oledAddr,
        Width:   screenW,
        Height:  screenH,
    })

    // ── Startup splash ─────────────────────────────────────────────────
    drawSplash(&display)
    display.Display()
    time.Sleep(2 * time.Second)

    println("[OLED ] Display initialized")

    // ── Main refresh loop ──────────────────────────────────────────────
    // Structure mirrors display.rs oled_task loop and
    // display_poll() timing logic in display.c.
    //
    // TinyGo advantage over C here:
    //   time.Sleep(100ms) yields this goroutine — sensor goroutines
    //   continue running. In C, display_poll() returns immediately
    //   when not due — the main loop spins doing nothing useful.

    var (
        currentPage page   = pageSensors
        pageTickCnt uint32 = 0
        tick        uint32 = 0
    )

    for {
        s := getState() // snapshot — same pattern as Rust + C

        display.ClearDisplay()

        switch currentPage {
        case pageSensors:
            drawSensorsPage(&display, &s, tick)
        case pageStatus:
            drawStatusPage(&display, &s)
        }

        // Flush framebuffer to display over I2C
        // Equivalent to:
        //   Rust:   display.flush().ok()
        //   C:      ssd1306_flush_all()
        display.Display()

        pageTickCnt++
        if pageTickCnt >= pageTicks {
            pageTickCnt = 0
            currentPage = currentPage.next()
        }

        tick++

        // Yield to scheduler — other goroutines run during this sleep.
        // Rust: Timer::after(Duration::from_millis(100)).await
        // C:    return from display_poll(), main loop continues
        time.Sleep(100 * time.Millisecond)
    }
}

// ── Page renderers ─────────────────────────────────────────────────────────

// drawSensorsPage renders page 0.
//
// ┌────────────────────────┐
// │ BASEMENT MONITOR       │  ← inverted title bar
// │ Water: DRY             │  ← flashes when wet
// │ Temp:  21.5 C          │
// │ Humid: 62.0 %          │  ← inverted when > 85%
// │ Alarm: OFF             │  ← inverted when active
// │                  • ○   │  ← page indicator
// └────────────────────────┘

func drawSensorsPage(
    d   *ssd1306.Device,
    s   *sensors.SensorState,
    tick uint32,
) {
    // ── Title bar ──────────────────────────────────────────────────────
    drawTitleBar(d, "BASEMENT MONITOR")

    // ── Water status ───────────────────────────────────────────────────
    // Flash every other tick (100ms period) matching display.rs and display.c
    if s.WaterDetected {
        flashOn := tick%2 == 0
        if flashOn {
            fillRect(d, 0, row1, screenW, 8, colorOn)
        }
        drawString(d, 2, row1+7, "Water: !! WET !!", flashOn)
    } else {
        drawString(d, 2, row1+7, "Water: DRY", false)
    }

    // ── Temperature ────────────────────────────────────────────────────
    // fmt.Sprintf allocates here — GC cost.
    // Rust uses write!(heapless::String, ...) — zero allocation.
    // C uses snprintf into stack buffer — zero allocation.
    // At 100ms refresh frequency the GC cost is negligible.
    drawString(d, 2, row2+7,
        fmt.Sprintf("Temp:  %.1f C", s.TemperatureC),
        false)

    // ── Humidity ───────────────────────────────────────────────────────
    humWarn := s.HumidityPct > 85.0
    if humWarn {
        fillRect(d, 0, row3, screenW, 8, colorOn)
    }
    drawString(d, 2, row3+7,
        fmt.Sprintf("Humid: %.1f %%", s.HumidityPct),
        humWarn)

    // ── Alarm status ───────────────────────────────────────────────────
    if s.AlarmActive {
        fillRect(d, 0, row4, screenW, 8, colorOn)
        drawString(d, 2, row4+7, "Alarm: ACTIVE", true)
    } else {
        drawString(d, 2, row4+7, "Alarm: OFF", false)
    }

    // ── Page indicator ─────────────────────────────────────────────────
    drawPageIndicator(d, pageSensors, pageCount)
}

// drawStatusPage renders page 1.
//
// ┌────────────────────────┐
// │ STATUS                 │  ← inverted title bar
// │ Motion: CLEAR          │
// │ CO:    12 ppm  OK      │  ← inverted entire row when DANGER
// │ [=======    ]          │  ← CO bar graph 0-300ppm
// │ Net: 192.168.1.42      │
// │                  ○ •   │  ← page indicator
// └────────────────────────┘

func drawStatusPage(d *ssd1306.Device, s *sensors.SensorState) {
    // ── Title bar ──────────────────────────────────────────────────────
    drawTitleBar(d, "STATUS")

    // ── Motion ─────────────────────────────────────────────────────────
    motionText := "Motion: CLEAR"
    if s.MotionDetected {
        motionText = "Motion: DETECTED"
    }
    drawString(d, 2, row1+7, motionText, false)

    // ── CO level + severity ────────────────────────────────────────────
    var severity string
    coDanger := false

    switch {
    case s.CoPpm >= 150:
        severity = "DANGER"
        coDanger = true
    case s.CoPpm >= 50:
        severity = "WARN"
    default:
        severity = "OK"
    }

    coText := fmt.Sprintf("CO: %d ppm %s", s.CoPpm, severity)

    if coDanger {
        fillRect(d, 0, row2, screenW, 8, colorOn)
    }
    drawString(d, 2, row2+7, coText, coDanger)

    // ── CO bar graph ───────────────────────────────────────────────────
    // 0-300ppm range, 124px wide.
    // Same bar graph as display.rs fb_draw_bar() and display.c fb_draw_bar().
    drawBarGraph(d, row3, s.CoPpm, 300)

    // ── Network IP ─────────────────────────────────────────────────────
    // wifi.GetIP() returns the cached IP string set at connection time.
    // Avoids a network call from the display goroutine.
    ip := wifi_GetIP() // forward declaration — implemented in wifi/wifi.go
    drawString(d, 2, row4+7, fmt.Sprintf("Net: %s", ip), false)

    // ── Page indicator ─────────────────────────────────────────────────
    drawPageIndicator(d, pageStatus, pageCount)
}

// ── Splash screen ──────────────────────────────────────────────────────────

// drawSplash renders the 2-second startup screen.
// Matches draw_splash() in display.rs and display_draw_splash() in display.c.
//
// ┌────────────────────────┐
// │                        │
// │      Basement          │
// │       Monitor          │
// │ ────────────────────── │
// │    TinyGo + Pico W     │
// └────────────────────────┘

func drawSplash(d *ssd1306.Device) {
    d.ClearDisplay()

    drawString(d, 16, row1+7, "Basement", false)
    drawString(d, 22, row3+7, "Monitor",  false)

    // Horizontal divider
    hline(d, 0, row5, screenW, colorOn)

    drawString(d, 4, row6+7, "TinyGo + Pico W", false)
}

// ── Shared UI widgets ──────────────────────────────────────────────────────

// drawTitleBar fills a full-width inverted bar and draws white-on-black text.
// Equivalent to fb_draw_title_bar() in display.c and the Rectangle +
// inverted MonoTextStyle pattern in display.rs.
func drawTitleBar(d *ssd1306.Device, title string) {
    fillRect(d, 0, row0, screenW, 8, colorOn)
    drawString(d, 2, row0+7, title, true)
}

// drawPageIndicator renders filled/outline dots at bottom-right.
// Matches draw_page_indicator() in display.rs and fb_draw_page_indicator()
// in display.c exactly — same dot size, spacing, and position logic.
//
//   filled square  = current page
//   outline square = other page
func drawPageIndicator(d *ssd1306.Device, current page, total int) {
    dotSize    := int16(4)
    dotSpacing := int16(8)
    startX     := int16(screenW) - int16(total)*dotSpacing - 4
    y           := int16(screenH) - 6

    for i := 0; i < total; i++ {
        x := startX + int16(i)*dotSpacing
        if page(i) == current {
            // Filled square — current page
            fillRect(d, int(x), int(y), int(dotSize), int(dotSize), colorOn)
        } else {
            // Outline square — other page
            // Top and bottom edges
            hline(d, int(x), int(y),              int(dotSize), colorOn)
            hline(d, int(x), int(y)+int(dotSize)-1, int(dotSize), colorOn)
            // Left and right edges
            for row := int(y); row < int(y)+int(dotSize); row++ {
                d.SetPixel(x,              int16(row), colorOn)
                d.SetPixel(x+dotSize-1,   int16(row), colorOn)
            }
        }
    }
}

// drawBarGraph renders a horizontal progress bar.
// Matches fb_draw_bar() in display.c and the Rectangle bar in display.rs.
//
// barY:    top pixel row of the bar
// value:   current reading
// maxVal:  value that represents a full bar (124px wide)
//
// Outline is always drawn. Fill is proportional to value/maxVal.
func drawBarGraph(d *ssd1306.Device, barY int, value uint16, maxVal uint16) {
    const barMaxW = 124
    const barH    = 8

    barW := int(uint32(value) * barMaxW / uint32(maxVal))
    if barW > barMaxW {
        barW = barMaxW
    }

    // Outline rectangle
    // Top edge
    hline(d, 2, barY,         barMaxW, colorOn)
    // Bottom edge
    hline(d, 2, barY+barH-1,  barMaxW, colorOn)
    // Left and right edges
    for row := barY; row < barY+barH; row++ {
        d.SetPixel(2,             int16(row), colorOn)
        d.SetPixel(2+barMaxW-1,   int16(row), colorOn)
    }

    // Fill — proportional to value
    if barW > 0 {
        fillRect(d, 2, barY, barW, barH, colorOn)
    }
}

// DrawError renders a full-screen inverted error message.
// Exported so other packages (sensors, wifi) can call it.
// Matches draw_error() in display.rs and display_error() in display.c.
//
// message: up to 42 characters, word-wrapped across two lines.
//
// ┌────────────────────────┐
// │████████████████████████│  ← full white screen
// │███ ERROR ██████████████│
// │████████████████████████│
// │███ line 1 █████████████│
// │███ line 2 █████████████│
// │████████████████████████│
// └────────────────────────┘
func DrawError(d *ssd1306.Device, message string) {
    d.ClearDisplay()

    // Full screen white background
    fillRect(d, 0, 0, screenW, screenH, colorOn)

    // "ERROR" in black-on-white
    drawString(d, 40, row1+7, "ERROR", true)

    // Black horizontal divider on white background
    hline(d, 0, row3, screenW, colorOff)

    // Word-wrap message across two lines (21 chars each)
    const lineLen = 21
    runes := []rune(message)

    line1 := string(runes[:min(lineLen, len(runes))])
    line2 := ""
    if len(runes) > lineLen {
        end := lineLen + lineLen
        if end > len(runes) {
            end = len(runes)
        }
        line2 = string(runes[lineLen:end])
    }

    // Black text on white background (inverted = true)
    drawString(d, 2, row4+7, line1, true)
    if line2 != "" {
        drawString(d, 2, row5+7, line2, true)
    }

    d.Display()
    println("[OLED ] Error displayed:", message)
}

// ── Low-level drawing primitives ───────────────────────────────────────────
// These wrap ssd1306.Device.SetPixel() to provide the same rectangle,
// line, and text primitives that display.c implements manually against
// g_framebuffer and that display.rs gets from embedded-graphics.

// fillRect fills a rectangle with the given color.
// Equivalent to:
//   Rust:   Rectangle::new(Point, Size).into_styled(fill).draw(display)
//   C:      fb_fill_rect(x, y, w, h, on)
func fillRect(d *ssd1306.Device, x, y, w, h int, color ssd1306.Color) {
    for row := y; row < y+h; row++ {
        for col := x; col < x+w; col++ {
            d.SetPixel(int16(col), int16(row), color)
        }
    }
}

// hline draws a horizontal line.
// Equivalent to:
//   Rust:   Line::new(Point, Point).into_styled(stroke).draw(display)
//   C:      fb_hline(x, y, w, on)
func hline(d *ssd1306.Device, x, y, w int, color ssd1306.Color) {
    for col := x; col < x+w; col++ {
        d.SetPixel(int16(col), int16(y), color)
    }
}

// drawString renders a string using tinyfont at pixel position (x, y).
// y is the baseline position — tinyfont renders upward from baseline.
//
// inverted:
//   false = white text on black background (normal)
//   true  = black text on white background (alert/title bar)
//
// Comparison:
//   Rust:   Text::with_baseline(str, Point, MonoTextStyleBuilder...build())
//           MonoTextStyleBuilder sets text_color + background_color
//   C:      fb_draw_str(x, y, str, inverted)
//           Manual font table lookup, XOR 0xFF for inversion
//   TinyGo: tinyfont.WriteLine() — same font table approach as C
//           but packaged as a library rather than embedded in display.c
//
// tinyfont note:
//   tinyfont.WriteLine renders at pixel-level using SetPixel callbacks.
//   It does NOT allocate. The string is iterated as-is.
//   This is the zero-allocation equivalent for glyph rendering —
//   the fmt.Sprintf() calls above this layer are where allocation happens.
func drawString(d *ssd1306.Device, x, y int, text string, inverted bool) {
    fg := colorOn
    bg := colorOff

    if inverted {
        fg = colorOff
        bg = colorOn
    }

    // tinyfont.WriteLine signature:
    //   func WriteLine(display Displayer, font *tinyfont.Font,
    //                  x, y int16, str string, c color.RGBA)
    //
    // We use freemono.Regular7pt — a monospace font close to the
    // 6×8 font used in display.c and FONT_6X10 in display.rs.
    // The Displayer interface requires SetPixel(x, y int16, c color.RGBA)
    // which ssd1306.Device satisfies.

    // Fill background rectangle first if inverted so the
    // background color shows behind the glyphs.
    // Measure text width: freemono.Regular7pt is 6px per char
    if inverted {
        textW := len(text) * 6
        fillRect(d, x, y-7, textW, 8, colorOn)
    }

    tinyfont.WriteLine(
        d,
        &freemono.Regular7pt7b,
        int16(x),
        int16(y),
        text,
        fg.RGBA(),
    )
}

// ── WiFi IP helper ─────────────────────────────────────────────────────────
// Forward reference to wifi package — avoids import cycle.
// In a full implementation use a shared package-level var or
// pass the IP string into OLEDTask as a func() string parameter
// the same way getState is passed.

// wifi_GetIP is a shim — replace with an actual import or
// pass ip as a parameter to OLEDTask for cleaner architecture.
// Shown as a variable here to avoid import cycle in the example.
var wifi_GetIP = func() string {
    return "192.168.1.x"
}

// SetWifiIP updates the IP string shown on the status page.
// Call this from wifi.Connect() after obtaining a DHCP address.
//
// Usage in wifi/wifi.go:
//   display.SetWifiIP(ip)
func SetWifiIP(ip string) {
    wifi_GetIP = func() string { return ip }
}

// ── Utility ────────────────────────────────────────────────────────────────

func min(a, b int) int {
    if a < b {
        return a
    }
    return b
}

`display.h`| `display.c` Implementation

// display.h
#ifndef DISPLAY_H
#define DISPLAY_H

#include <stdbool.h>
#include <stdint.h>
#include "hardware/i2c.h"
#include "sensors.h"

// ── Pin assignments ────────────────────────────────────────────────────────
#define DISPLAY_I2C_PORT    i2c0
#define DISPLAY_I2C_SDA     6
#define DISPLAY_I2C_SCL     7
#define DISPLAY_I2C_FREQ    400000   // 400kHz fast mode
#define DISPLAY_I2C_ADDR    0x3C     // try 0x3D if this doesn't work

// ── Screen dimensions ──────────────────────────────────────────────────────
#define SCREEN_W            128
#define SCREEN_H            64
#define SCREEN_PAGES        8        // 64px / 8px per page = 8 i2c pages
                                    // (SSD1306 "page" = 8 pixel rows)

// ── Font dimensions (6x8 built-in SSD1306 font) ───────────────────────────
#define FONT_W              6
#define FONT_H              8
#define CHARS_PER_ROW       21       // 128 / 6 = 21 chars
#define ROWS_PER_SCREEN     8        // 64  / 8 = 8 rows

// ── Row Y positions (pixel rows, multiples of 8) ──────────────────────────
#define ROW_0               0
#define ROW_1               8
#define ROW_2               16
#define ROW_3               24
#define ROW_4               32
#define ROW_5               40
#define ROW_6               48
#define ROW_7               56

// ── Display pages (same two-page model as display.rs) ─────────────────────
typedef enum {
   PAGE_SENSORS = 0,   // water, temp, humidity, alarm
   PAGE_STATUS  = 1,   // motion, CO bar graph, network
   PAGE_COUNT   = 2,
} DisplayPage;

// ── SSD1306 commands ───────────────────────────────────────────────────────
// Subset of the SSD1306 command set used in initialization and rendering.
// Full datasheet: https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf

#define SSD1306_CMD_DISPLAY_OFF         0xAE
#define SSD1306_CMD_DISPLAY_ON          0xAF
#define SSD1306_CMD_SET_CONTRAST        0x81
#define SSD1306_CMD_ENTIRE_ON           0xA5
#define SSD1306_CMD_ENTIRE_RESUME       0xA4
#define SSD1306_CMD_NORMAL_DISPLAY      0xA6
#define SSD1306_CMD_INVERT_DISPLAY      0xA7
#define SSD1306_CMD_SET_MEM_MODE        0x20
#define SSD1306_CMD_SET_COL_ADDR        0x21
#define SSD1306_CMD_SET_PAGE_ADDR       0x22
#define SSD1306_CMD_SET_DISP_START_LINE 0x40
#define SSD1306_CMD_SET_SEG_REMAP       0xA0
#define SSD1306_CMD_SET_MUX_RATIO       0xA8
#define SSD1306_CMD_COM_OUT_SCAN_DIR    0xC0
#define SSD1306_CMD_SET_DISP_OFFSET     0xD3
#define SSD1306_CMD_SET_COM_PIN_CFG     0xDA
#define SSD1306_CMD_SET_DISP_CLK_DIV   0xD5
#define SSD1306_CMD_SET_PRECHARGE       0xD9
#define SSD1306_CMD_SET_VCOM_DESEL      0xDB
#define SSD1306_CMD_CHARGE_PUMP         0x8D
#define SSD1306_CMD_NOP                 0xE3

// ── Framebuffer ───────────────────────────────────────────────────────────
// 128 × 64 pixels = 8192 bits = 1024 bytes.
// Organized as 8 pages × 128 columns.
// Each byte represents 8 vertical pixels in one column of one page.
// Bit 0 = top pixel of the byte, bit 7 = bottom pixel.
//
// This mirrors the Rust implementation's BufferedGraphicsMode —
// both keep a full framebuffer in RAM and flush to the display
// in one I2C transaction. The C version manages this buffer manually.
// Rust's ssd1306 crate manages it internally with the same layout.
extern uint8_t g_framebuffer[SCREEN_H / 8][SCREEN_W];

// ── Public API ─────────────────────────────────────────────────────────────

// Initialization
bool     display_init(void);

// Main poll function — call from main loop every iteration.
// Handles page rotation timing and refresh cadence internally.
// Never blocks — returns immediately if it's not time to refresh.
void     display_poll(void);

// Force an immediate refresh with the given state snapshot.
// Used when you want to update the display outside the normal cadence
// (e.g. immediately after a water detection event).
void     display_force_update(const SensorState *s);

// Show a full-screen error message. Blocks until next display_poll() cycle.
// message: up to 42 characters, word-wrapped across two lines.
void     display_error(const char *message);

// ── Internal rendering functions (exposed for testing) ────────────────────
void     display_draw_sensors_page(const SensorState *s, uint32_t tick);
void     display_draw_status_page(const SensorState *s);
void     display_draw_splash(void);

#endif // DISPLAY_H

// display.c
//
// SSD1306 128x64 OLED display driver over I2C.
// Implements the same two-page rotating UI as display.rs:
//
//   Page 0 (Sensors): water, temperature, humidity, alarm
//   Page 1 (Status):  motion, CO bar graph, network IP
//
// Architecture comparison:
//
//   Rust: embedded-graphics crate provides Point, Rectangle, Text primitives.
//         ssd1306 crate manages the framebuffer and flush.
//         heapless::String for zero-allocation string formatting.
//         Compiler enforces I2C peripheral exclusive ownership.
//
//   C:    We implement the framebuffer, font rendering, and primitives
//         entirely from scratch. No external library required beyond
//         the Pico SDK's hardware/i2c.h.
//         snprintf() for string formatting — stack allocated, no heap.
//         Nothing prevents two functions from using I2C simultaneously.
//         The programmer enforces this by convention.
//
//   TinyGo: tinygo/x/drivers/ssd1306 package — similar to Rust's crate.
//           fmt.Sprintf() allocates on the heap — triggers GC.
//           Goroutine owns the display — scheduler enforces single access.

#include "display.h"
#include "sensors.h"
#include "pico/stdlib.h"
#include "hardware/i2c.h"
#include <stdio.h>
#include <string.h>
#include <stdarg.h>

// ── Framebuffer ────────────────────────────────────────────────────────────
// 1024 bytes live in RAM for the duration of the program.
// On a Pico W with 264KB RAM this is negligible.
// On a smaller AVR (2KB RAM) this would be the majority of available memory —
// one reason SSD1306 is typically used with larger MCUs.
uint8_t g_framebuffer[SCREEN_H / 8][SCREEN_W];

// ── Built-in 6×8 font ─────────────────────────────────────────────────────
// Each character is 6 bytes wide × 8 bits tall.
// Bit layout: each byte is one column, bit 0 = top pixel.
// This is the standard SSD1306 font used in most embedded C drivers.
// 96 printable ASCII characters starting at 0x20 (space).
//
// In Rust: embedded-graphics provides FONT_6X10, FONT_9X15_BOLD etc.
//          as compile-time const data — same idea, more options.
// In TinyGo: tinygo/x/drivers uses the same font table internally.
// In C: we embed it directly — full control, no dependency.

static const uint8_t FONT_6X8[96][6] = {
    {0x00,0x00,0x00,0x00,0x00,0x00}, // 0x20 space
    {0x00,0x00,0x5F,0x00,0x00,0x00}, // 0x21 !
    {0x00,0x07,0x00,0x07,0x00,0x00}, // 0x22 "
    {0x14,0x7F,0x14,0x7F,0x14,0x00}, // 0x23 #
    {0x24,0x2A,0x7F,0x2A,0x12,0x00}, // 0x24 $
    {0x23,0x13,0x08,0x64,0x62,0x00}, // 0x25 %
    {0x36,0x49,0x55,0x22,0x50,0x00}, // 0x26 &
    {0x00,0x05,0x03,0x00,0x00,0x00}, // 0x27 '
    {0x00,0x1C,0x22,0x41,0x00,0x00}, // 0x28 (
    {0x00,0x41,0x22,0x1C,0x00,0x00}, // 0x29 )
    {0x08,0x2A,0x1C,0x2A,0x08,0x00}, // 0x2A *
    {0x08,0x08,0x3E,0x08,0x08,0x00}, // 0x2B +
    {0x00,0x50,0x30,0x00,0x00,0x00}, // 0x2C ,
    {0x08,0x08,0x08,0x08,0x08,0x00}, // 0x2D -
    {0x00,0x60,0x60,0x00,0x00,0x00}, // 0x2E .
    {0x20,0x10,0x08,0x04,0x02,0x00}, // 0x2F /
    {0x3E,0x51,0x49,0x45,0x3E,0x00}, // 0x30 0
    {0x00,0x42,0x7F,0x40,0x00,0x00}, // 0x31 1
    {0x42,0x61,0x51,0x49,0x46,0x00}, // 0x32 2
    {0x21,0x41,0x45,0x4B,0x31,0x00}, // 0x33 3
    {0x18,0x14,0x12,0x7F,0x10,0x00}, // 0x34 4
    {0x27,0x45,0x45,0x45,0x39,0x00}, // 0x35 5
    {0x3C,0x4A,0x49,0x49,0x30,0x00}, // 0x36 6
    {0x01,0x71,0x09,0x05,0x03,0x00}, // 0x37 7
    {0x36,0x49,0x49,0x49,0x36,0x00}, // 0x38 8
    {0x06,0x49,0x49,0x29,0x1E,0x00}, // 0x39 9
    {0x00,0x36,0x36,0x00,0x00,0x00}, // 0x3A :
    {0x00,0x56,0x36,0x00,0x00,0x00}, // 0x3B ;
    {0x00,0x08,0x14,0x22,0x41,0x00}, // 0x3C <
    {0x14,0x14,0x14,0x14,0x14,0x00}, // 0x3D =
    {0x41,0x22,0x14,0x08,0x00,0x00}, // 0x3E >
    {0x02,0x01,0x51,0x09,0x06,0x00}, // 0x3F ?
    {0x32,0x49,0x79,0x41,0x3E,0x00}, // 0x40 @
    {0x7E,0x11,0x11,0x11,0x7E,0x00}, // 0x41 A
    {0x7F,0x49,0x49,0x49,0x36,0x00}, // 0x42 B
    {0x3E,0x41,0x41,0x41,0x22,0x00}, // 0x43 C
    {0x7F,0x41,0x41,0x22,0x1C,0x00}, // 0x44 D
    {0x7F,0x49,0x49,0x49,0x41,0x00}, // 0x45 E
    {0x7F,0x09,0x09,0x01,0x01,0x00}, // 0x46 F
    {0x3E,0x41,0x41,0x49,0x7A,0x00}, // 0x47 G
    {0x7F,0x08,0x08,0x08,0x7F,0x00}, // 0x48 H
    {0x00,0x41,0x7F,0x41,0x00,0x00}, // 0x49 I
    {0x20,0x40,0x41,0x3F,0x01,0x00}, // 0x4A J
    {0x7F,0x08,0x14,0x22,0x41,0x00}, // 0x4B K
    {0x7F,0x40,0x40,0x40,0x40,0x00}, // 0x4C L
    {0x7F,0x02,0x04,0x02,0x7F,0x00}, // 0x4D M
    {0x7F,0x04,0x08,0x10,0x7F,0x00}, // 0x4E N
    {0x3E,0x41,0x41,0x41,0x3E,0x00}, // 0x4F O
    {0x7F,0x09,0x09,0x09,0x06,0x00}, // 0x50 P
    {0x3E,0x41,0x51,0x21,0x5E,0x00}, // 0x51 Q
    {0x7F,0x09,0x19,0x29,0x46,0x00}, // 0x52 R
    {0x46,0x49,0x49,0x49,0x31,0x00}, // 0x53 S
    {0x01,0x01,0x7F,0x01,0x01,0x00}, // 0x54 T
    {0x3F,0x40,0x40,0x40,0x3F,0x00}, // 0x55 U
    {0x1F,0x20,0x40,0x20,0x1F,0x00}, // 0x56 V
    {0x3F,0x40,0x38,0x40,0x3F,0x00}, // 0x57 W
    {0x63,0x14,0x08,0x14,0x63,0x00}, // 0x58 X
    {0x03,0x04,0x78,0x04,0x03,0x00}, // 0x59 Y
    {0x61,0x51,0x49,0x45,0x43,0x00}, // 0x5A Z
    {0x00,0x00,0x7F,0x41,0x41,0x00}, // 0x5B [
    {0x02,0x04,0x08,0x10,0x20,0x00}, // 0x5C backslash
    {0x41,0x41,0x7F,0x00,0x00,0x00}, // 0x5D ]
    {0x04,0x02,0x01,0x02,0x04,0x00}, // 0x5E ^
    {0x40,0x40,0x40,0x40,0x40,0x00}, // 0x5F _
    {0x00,0x01,0x02,0x04,0x00,0x00}, // 0x60 `
    {0x20,0x54,0x54,0x54,0x78,0x00}, // 0x61 a
    {0x7F,0x48,0x44,0x44,0x38,0x00}, // 0x62 b
    {0x38,0x44,0x44,0x44,0x20,0x00}, // 0x63 c
    {0x38,0x44,0x44,0x48,0x7F,0x00}, // 0x64 d
    {0x38,0x54,0x54,0x54,0x18,0x00}, // 0x65 e
    {0x08,0x7E,0x09,0x01,0x02,0x00}, // 0x66 f
    {0x08,0x54,0x54,0x54,0x3C,0x00}, // 0x67 g
    {0x7F,0x08,0x04,0x04,0x78,0x00}, // 0x68 h
    {0x00,0x44,0x7D,0x40,0x00,0x00}, // 0x69 i
    {0x20,0x40,0x44,0x3D,0x00,0x00}, // 0x6A j
    {0x00,0x7F,0x10,0x28,0x44,0x00}, // 0x6B k
    {0x00,0x41,0x7F,0x40,0x00,0x00}, // 0x6C l
    {0x7C,0x04,0x18,0x04,0x78,0x00}, // 0x6D m
    {0x7C,0x08,0x04,0x04,0x78,0x00}, // 0x6E n
    {0x38,0x44,0x44,0x44,0x38,0x00}, // 0x6F o
    {0x7C,0x14,0x14,0x14,0x08,0x00}, // 0x70 p
    {0x08,0x14,0x14,0x18,0x7C,0x00}, // 0x71 q
    {0x7C,0x08,0x04,0x04,0x08,0x00}, // 0x72 r
    {0x48,0x54,0x54,0x54,0x20,0x00}, // 0x73 s
    {0x04,0x3F,0x44,0x40,0x20,0x00}, // 0x74 t
    {0x3C,0x40,0x40,0x40,0x3C,0x00}, // 0x75 u
    {0x1C,0x20,0x40,0x20,0x1C,0x00}, // 0x76 v
    {0x3C,0x40,0x30,0x40,0x3C,0x00}, // 0x77 w
    {0x44,0x28,0x10,0x28,0x44,0x00}, // 0x78 x
    {0x0C,0x50,0x50,0x50,0x3C,0x00}, // 0x79 y
    {0x44,0x64,0x54,0x4C,0x44,0x00}, // 0x7A z
    {0x00,0x08,0x36,0x41,0x00,0x00}, // 0x7B {
    {0x00,0x00,0x7F,0x00,0x00,0x00}, // 0x7C |
    {0x00,0x41,0x36,0x08,0x00,0x00}, // 0x7D }
    {0x08,0x08,0x2A,0x1C,0x08,0x00}, // 0x7E ~
    {0x00,0x06,0x09,0x09,0x06,0x00}, // 0x7F DEG (degree symbol)
};

// ── Page rotation state ────────────────────────────────────────────────────
// In Rust this state lives inside the async task's stack frame —
// the task function is a state machine that preserves locals across .await.
// In C we use static locals — same effect, but global scope within the TU.

static DisplayPage g_current_page     = PAGE_SENSORS;
static uint32_t    g_page_ticks       = 0;
static uint32_t    g_tick             = 0;
static uint32_t    g_next_refresh_ms  = 0;

// Page rotation interval: 5000ms / 100ms per tick = 50 ticks
#define PAGE_TICKS  50

// ── Low-level I2C helpers ──────────────────────────────────────────────────

// Send a single command byte to the SSD1306.
// The 0x00 control byte tells SSD1306 the next byte is a command.
static void ssd1306_cmd(uint8_t cmd) {
    uint8_t buf[2] = {0x00, cmd};
    i2c_write_blocking(
        DISPLAY_I2C_PORT,
        DISPLAY_I2C_ADDR,
        buf, 2,
        false
    );
}

// Send two command bytes (command + argument).
static void ssd1306_cmd2(uint8_t cmd, uint8_t arg) {
    uint8_t buf[3] = {0x00, cmd, arg};
    i2c_write_blocking(
        DISPLAY_I2C_PORT,
        DISPLAY_I2C_ADDR,
        buf, 3,
        false
    );
}

// Flush one page (8 pixel rows) of the framebuffer to the display.
// The 0x40 control byte tells SSD1306 the following bytes are pixel data.
static void ssd1306_flush_page(uint8_t page) {
    // Set cursor to start of this page
    ssd1306_cmd2(SSD1306_CMD_SET_PAGE_ADDR, page);
    ssd1306_cmd2(SSD1306_CMD_SET_COL_ADDR,  0);

    // Prepend the 0x40 data control byte
    uint8_t buf[SCREEN_W + 1];
    buf[0] = 0x40;
    memcpy(buf + 1, g_framebuffer[page], SCREEN_W);

    i2c_write_blocking(
        DISPLAY_I2C_PORT,
        DISPLAY_I2C_ADDR,
        buf, sizeof(buf),
        false
    );
}

// Flush entire framebuffer to display — all 8 pages.
// Takes ~2ms at 400kHz I2C (1025 bytes × 8 pages).
// Identical cost to Rust's display.flush() and TinyGo's display.Display().
static void ssd1306_flush_all(void) {
    // Set horizontal addressing mode — auto-increments column then page
    ssd1306_cmd2(SSD1306_CMD_SET_MEM_MODE, 0x00);
    ssd1306_cmd2(SSD1306_CMD_SET_COL_ADDR, 0);
    ssd1306_cmd(0x7F);  // col end = 127
    ssd1306_cmd2(SSD1306_CMD_SET_PAGE_ADDR, 0);
    ssd1306_cmd(0x07);  // page end = 7

    // Send all pixel data in one transaction
    uint8_t buf[SCREEN_W * SCREEN_PAGES + 1];
    buf[0] = 0x40;
    for (int p = 0; p < SCREEN_PAGES; p++) {
        memcpy(buf + 1 + p * SCREEN_W, g_framebuffer[p], SCREEN_W);
    }

    i2c_write_blocking(
        DISPLAY_I2C_PORT,
        DISPLAY_I2C_ADDR,
        buf, sizeof(buf),
        false
    );
}

// ── Framebuffer primitives ─────────────────────────────────────────────────
// These implement the same operations as embedded-graphics in Rust.
// In Rust: Rectangle::new().into_styled().draw(&mut display)
// In C: fb_fill_rect() — direct framebuffer manipulation.
//
// The SSD1306 framebuffer layout:
//   g_framebuffer[page][col]
//   page = y / 8  (which group of 8 pixel rows)
//   col  = x      (which column 0-127)
//   bit  = y % 8  (which pixel within the page byte)

// Set or clear a single pixel in the framebuffer.
static void fb_set_pixel(int x, int y, bool on) {
    if (x < 0 || x >= SCREEN_W || y < 0 || y >= SCREEN_H) return;
    uint8_t page = y / 8;
    uint8_t bit  = y % 8;
    if (on) {
        g_framebuffer[page][x] |=  (1 << bit);
    } else {
        g_framebuffer[page][x] &= ~(1 << bit);
    }
}

// Fill a rectangle with on or off pixels.
// Equivalent to:
//   Rust: Rectangle::new(Point, Size).into_styled(fill_style).draw()
//   TinyGo: no direct primitive — would loop pixels
static void fb_fill_rect(int x, int y, int w, int h, bool on) {
    for (int row = y; row < y + h; row++) {
        for (int col = x; col < x + w; col++) {
            fb_set_pixel(col, row, on);
        }
    }
}

// Draw a horizontal line — optimized vs fb_fill_rect for single-pixel height.
static void fb_hline(int x, int y, int w, bool on) {
    for (int col = x; col < x + w; col++) {
        fb_set_pixel(col, y, on);
    }
}

// Clear the entire framebuffer (all pixels off).
static void fb_clear(void) {
    memset(g_framebuffer, 0, sizeof(g_framebuffer));
}

// ── Character and string rendering ────────────────────────────────────────

// Draw a single character at pixel position (x, y).
// inverted: true = black text on white background (alert style)
//           false = white text on black background (normal style)
//
// In Rust: MonoTextStyleBuilder with text_color / background_color
// In TinyGo: ssd1306 driver handles this internally
// In C: we XOR each font byte against 0xFF to invert
static void fb_draw_char(int x, int y, char c, bool inverted) {
    if (c < 0x20 || c > 0x7F) c = '?';
    const uint8_t *glyph = FONT_6X8[c - 0x20];

    for (int col = 0; col < 6; col++) {
        uint8_t column_data = glyph[col];
        if (inverted) column_data = ~column_data;

        for (int row = 0; row < 8; row++) {
            fb_set_pixel(x + col, y + row, (column_data >> row) & 1);
        }
    }
}

// Draw a string at pixel position (x, y).
// Clips at screen edge — no wrapping.
static void fb_draw_str(int x, int y, const char *str, bool inverted) {
    int cx = x;
    while (*str && cx + FONT_W <= SCREEN_W) {
        fb_draw_char(cx, y, *str, inverted);
        cx  += FONT_W;
        str ++;
    }
}

// Draw a formatted string — thin wrapper around snprintf + fb_draw_str.
// buf_size should be at least CHARS_PER_ROW + 1.
//
// In Rust: write!(heapless::String, format_args!(...)) — zero allocation
// In C:    snprintf into stack buffer — zero heap allocation, same safety
//          profile for bounded sizes. UB if format produces > buf_size chars.
static void fb_draw_fmt(int x, int y, bool inverted,
                        char *buf, size_t buf_size,
                        const char *fmt, ...) {
    va_list args;
    va_start(args, fmt);
    vsnprintf(buf, buf_size, fmt, args);
    va_end(args);
    fb_draw_str(x, y, buf, inverted);
}

// Draw a filled inverted title bar spanning the full screen width.
// Equivalent to the Rectangle + inverted text pattern in display.rs.
static void fb_draw_title_bar(const char *title) {
    fb_fill_rect(0, ROW_0, SCREEN_W, FONT_H, true);  // white bar
    fb_draw_str(2, ROW_0, title, true);               // black text on white
}

// Draw page indicator dots — same logic as display.rs draw_page_indicator().
// Filled square = current page. Outline square = other page.
// Positioned at bottom-right of screen.
static void fb_draw_page_indicator(uint8_t current, uint8_t total) {
    int dot_size    = 4;
    int dot_spacing = 8;
    int start_x     = SCREEN_W - (total * dot_spacing) - 4;
    int y           = SCREEN_H - 6;

    for (int i = 0; i < total; i++) {
        int x = start_x + i * dot_spacing;
        if (i == current) {
            // Filled square = current page
            fb_fill_rect(x, y, dot_size, dot_size, true);
        } else {
            // Outline square = other page
            // Draw 4 sides of the rectangle manually
            fb_hline(x,               y,               dot_size, true); // top
            fb_hline(x,               y + dot_size - 1, dot_size, true); // bottom
            for (int row = y; row < y + dot_size; row++) {
                fb_set_pixel(x,               row, true); // left
                fb_set_pixel(x + dot_size - 1, row, true); // right
            }
        }
    }
}

// Draw a CO bar graph.
// Identical to the Rectangle bar graph in display.rs draw_status_page().
// max_val: the PPM value that represents a full bar.
// bar spans columns 2-125 (124px wide).
static void fb_draw_bar(int y, uint16_t value, uint16_t max_val) {
    int bar_max_w = 124;
    int bar_w     = (int)((uint32_t)value * bar_max_w / max_val);
    if (bar_w > bar_max_w) bar_w = bar_max_w;

    // Outline
    for (int col = 2; col < 2 + bar_max_w; col++) {
        fb_set_pixel(col, y,     true);  // top edge
        fb_set_pixel(col, y + 7, true);  // bottom edge
    }
    fb_set_pixel(2,               y, true);
    fb_set_pixel(2,               y + 7, true);
    for (int row = y; row <= y + 7; row++) {
        fb_set_pixel(2,                row, true);  // left edge
        fb_set_pixel(2 + bar_max_w - 1, row, true); // right edge
    }

    // Fill
    if (bar_w > 0) {
        fb_fill_rect(2, y, bar_w, 8, true);
    }
}

// ── SSD1306 initialization sequence ───────────────────────────────────────
// This sequence follows the SSD1306 application note exactly.
// Same initialization in all three languages — C makes it explicit,
// Rust's ssd1306 crate does it inside init(), TinyGo's driver does the same.

static bool ssd1306_init_sequence(void) {
    // Test I2C connectivity with a zero-length write
    int result = i2c_write_blocking(
        DISPLAY_I2C_PORT,
        DISPLAY_I2C_ADDR,
        NULL, 0,
        false
    );
    if (result == PICO_ERROR_GENERIC) {
        printf("[OLED ] No device at 0x%02X — check wiring\n",
               DISPLAY_I2C_ADDR);
        return false;
    }

    ssd1306_cmd(SSD1306_CMD_DISPLAY_OFF);
    ssd1306_cmd2(SSD1306_CMD_SET_DISP_CLK_DIV,   0x80);
    ssd1306_cmd2(SSD1306_CMD_SET_MUX_RATIO,       0x3F); // 64MUX
    ssd1306_cmd2(SSD1306_CMD_SET_DISP_OFFSET,     0x00);
    ssd1306_cmd(SSD1306_CMD_SET_DISP_START_LINE | 0x00);
    ssd1306_cmd2(SSD1306_CMD_CHARGE_PUMP,          0x14); // enable charge pump
    ssd1306_cmd2(SSD1306_CMD_SET_MEM_MODE,         0x00); // horizontal addressing
    ssd1306_cmd(SSD1306_CMD_SET_SEG_REMAP       | 0x01); // mirror horizontally
    ssd1306_cmd(SSD1306_CMD_COM_OUT_SCAN_DIR    | 0x08); // scan top to bottom
    ssd1306_cmd2(SSD1306_CMD_SET_COM_PIN_CFG,      0x12);
    ssd1306_cmd2(SSD1306_CMD_SET_CONTRAST,         0xCF);
    ssd1306_cmd2(SSD1306_CMD_SET_PRECHARGE,        0xF1);
    ssd1306_cmd2(SSD1306_CMD_SET_VCOM_DESEL,       0x40);
    ssd1306_cmd(SSD1306_CMD_ENTIRE_RESUME);              // use RAM content
    ssd1306_cmd(SSD1306_CMD_NORMAL_DISPLAY);             // not inverted
    ssd1306_cmd(SSD1306_CMD_DISPLAY_ON);

    return true;
}

// ── Page renderers ─────────────────────────────────────────────────────────

// Page 0 — Sensors
//
// ┌────────────────────────┐
// │ BASEMENT MONITOR       │  ← inverted title bar
// │ Water: DRY             │  ← flashes when wet
// │ Temp:  21.5 C          │
// │ Humid: 62.0 %          │  ← inverted when > 85%
// │ Alarm: OFF             │  ← inverted when active
// │                  • ○   │  ← page indicator
// └────────────────────────┘

void display_draw_sensors_page(const SensorState *s, uint32_t tick) {
    char buf[CHARS_PER_ROW + 2];

    // ── Title bar ──────────────────────────────────────────────────────
    fb_draw_title_bar("BASEMENT MONITOR");

    // ── Water status ───────────────────────────────────────────────────
    // Flash every other tick (100ms period) when water detected.
    // Equivalent to Rust's tick % 2 == 0 flashing logic.
    if (s->water_detected) {
        bool flash_on = (tick % 2 == 0);
        if (flash_on) {
            fb_fill_rect(0, ROW_1, SCREEN_W, FONT_H, true);
        }
        fb_draw_str(2, ROW_1, "Water: !! WET !!", flash_on);
    } else {
        fb_draw_str(2, ROW_1, "Water: DRY", false);
    }

    // ── Temperature ────────────────────────────────────────────────────
    // snprintf into stack buffer — same zero-heap approach as
    // Rust's heapless::String + write!() macro
    snprintf(buf, sizeof(buf), "Temp:  %.1f C", s->temperature_c);
    fb_draw_str(2, ROW_2, buf, false);

    // ── Humidity ───────────────────────────────────────────────────────
    snprintf(buf, sizeof(buf), "Humid: %.1f %%", s->humidity_pct);
    bool hum_warn = s->humidity_pct > 85.0f;
    if (hum_warn) {
        fb_fill_rect(0, ROW_3, SCREEN_W, FONT_H, true);
    }
    fb_draw_str(2, ROW_3, buf, hum_warn);

    // ── Alarm status ───────────────────────────────────────────────────
    if (s->alarm_active) {
        fb_fill_rect(0, ROW_4, SCREEN_W, FONT_H, true);
        fb_draw_str(2, ROW_4, "Alarm: ACTIVE", true);
    } else {
        fb_draw_str(2, ROW_4, "Alarm: OFF", false);
    }

    // ── Page indicator ─────────────────────────────────────────────────
    fb_draw_page_indicator(PAGE_SENSORS, PAGE_COUNT);
}

// Page 1 — Status
//
// ┌────────────────────────┐
// │ STATUS                 │  ← inverted title bar
// │ Motion: CLEAR          │
// │ CO:    12 ppm  OK      │  ← inverted entire row when DANGER
// │ [=======    ]          │  ← CO bar graph 0-300ppm
// │ Net: 192.168.1.42      │
// │                  ○ •   │  ← page indicator
// └────────────────────────┘

void display_draw_status_page(const SensorState *s) {
    char buf[CHARS_PER_ROW + 2];

    // ── Title bar ──────────────────────────────────────────────────────
    fb_draw_title_bar("STATUS");

    // ── Motion ─────────────────────────────────────────────────────────
    fb_draw_str(2, ROW_1,
        s->motion_detected ? "Motion: DETECTED" : "Motion: CLEAR",
        false);

    // ── CO level + severity ────────────────────────────────────────────
    const char *severity;
    bool co_danger = false;
    bool co_warn   = false;

    if (s->co_ppm >= 150) {
        severity  = "DANGER";
        co_danger = true;
    } else if (s->co_ppm >= 50) {
        severity = "WARN";
        co_warn  = true;
    } else {
        severity = "OK";
    }

    snprintf(buf, sizeof(buf), "CO: %u ppm %s", s->co_ppm, severity);

    if (co_danger) {
        fb_fill_rect(0, ROW_2, SCREEN_W, FONT_H, true);
    }
    fb_draw_str(2, ROW_2, buf, co_danger);

    // ── CO bar graph ───────────────────────────────────────────────────
    // 0–300 ppm range, 124px wide
    // Equivalent to the bar graph Rectangle in display.rs
    fb_draw_bar(ROW_3, s->co_ppm, 300);

    // ── Network IP ─────────────────────────────────────────────────────
    // In a full implementation retrieve actual IP from wifi module.
    // Stored as a static string updated by wifi_task on connect.
    extern char g_ip_address[16]; // defined in wifi.c
    snprintf(buf, sizeof(buf), "Net: %s", g_ip_address);
    fb_draw_str(2, ROW_4, buf, false);

    // ── Page indicator ─────────────────────────────────────────────────
    fb_draw_page_indicator(PAGE_STATUS, PAGE_COUNT);
}

// Startup splash screen — shown for 2 seconds at boot.
// Mirrors display.rs draw_splash().
//
// ┌────────────────────────┐
// │                        │
// │      Basement          │
// │       Monitor          │
// │ ────────────────────── │
// │    C + Pico SDK        │
// └────────────────────────┘

void display_draw_splash(void) {
    fb_clear();

    fb_draw_str(16, ROW_1, "Basement", false);
    fb_draw_str(22, ROW_3, "Monitor", false);

    // Horizontal divider at ROW_5
    fb_hline(0, ROW_5, SCREEN_W, true);

    fb_draw_str(10, ROW_6, "C + Pico SDK", false);

    ssd1306_flush_all();
}

// ── Public API implementation ──────────────────────────────────────────────

bool display_init(void) {
    // Initialize I2C hardware
    i2c_init(DISPLAY_I2C_PORT, DISPLAY_I2C_FREQ);

    gpio_set_function(DISPLAY_I2C_SDA, GPIO_FUNC_I2C);
    gpio_set_function(DISPLAY_I2C_SCL, GPIO_FUNC_I2C);
    gpio_pull_up(DISPLAY_I2C_SDA);
    gpio_pull_up(DISPLAY_I2C_SCL);

    // Clear framebuffer before init
    fb_clear();

    // Send SSD1306 init sequence
    if (!ssd1306_init_sequence()) {
        return false;
    }

    // Flush blank framebuffer to clear any garbage on screen
    ssd1306_flush_all();

    printf("[OLED ] Display initialized at I2C addr 0x%02X\n",
           DISPLAY_I2C_ADDR);

    // Show splash for 2 seconds
    // In C this blocks — other poll functions stop during splash.
    // In Rust the oled_task sleeps async — others continue.
    // In TinyGo the goroutine sleeps — others continue.
    // This is a minor difference acceptable at startup.
    display_draw_splash();
    sleep_ms(2000);

    return true;
}

void display_poll(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    // Refresh every 100ms — matches Rust's Timer::after(100ms)
    if (now < g_next_refresh_ms) return;
    g_next_refresh_ms = now + 100;

    // Snapshot state — same pattern as all three implementations
    state_lock();
    SensorState s = g_state;
    state_unlock();

    fb_clear();

    switch (g_current_page) {
        case PAGE_SENSORS:
            display_draw_sensors_page(&s, g_tick);
            break;
        case PAGE_STATUS:
            display_draw_status_page(&s);
            break;
        default:
            break;
    }

    ssd1306_flush_all();

    // Rotate page every PAGE_TICKS ticks
    g_page_ticks++;
    if (g_page_ticks >= PAGE_TICKS) {
        g_page_ticks  = 0;
        g_current_page = (g_current_page == PAGE_SENSORS)
                       ? PAGE_STATUS
                       : PAGE_SENSORS;
    }

    g_tick++;
}

void display_force_update(const SensorState *s) {
    fb_clear();

    switch (g_current_page) {
        case PAGE_SENSORS:
            display_draw_sensors_page(s, g_tick);
            break;
        case PAGE_STATUS:
            display_draw_status_page(s);
            break;
    }

    ssd1306_flush_all();
}

void display_error(const char *message) {
    fb_clear();

    // Full screen inverted box
    fb_fill_rect(0, 0, SCREEN_W, SCREEN_H, true);

    // "ERROR" title in black-on-white
    fb_draw_str(40, ROW_1, "ERROR", true);

    // Horizontal divider
    fb_hline(0, ROW_3, SCREEN_W, false); // black line on white background

    // Word-wrap message across two lines
    // Line 1: chars 0-20, Line 2: chars 21-41
    char line1[CHARS_PER_ROW + 1] = {0};
    char line2[CHARS_PER_ROW + 1] = {0};

    size_t msg_len = strlen(message);
    size_t l1_len  = msg_len < CHARS_PER_ROW ? msg_len : CHARS_PER_ROW;
    size_t l2_len  = msg_len > CHARS_PER_ROW
                   ? (msg_len - CHARS_PER_ROW < CHARS_PER_ROW
                      ? msg_len - CHARS_PER_ROW
                      : CHARS_PER_ROW)
                   : 0;

    strncpy(line1, message,               l1_len);
    strncpy(line2, message + CHARS_PER_ROW, l2_len);

    // Draw black text on white background (inverted = true)
    fb_draw_str(2, ROW_4, line1, true);
    if (l2_len > 0) {
        fb_draw_str(2, ROW_5, line2, true);
    }

    ssd1306_flush_all();

    printf("[OLED ] Error displayed: %s\n", message);
}

`display.rs` Implementation

// src/display.rs
//
// SSD1306 128x64 OLED display driver over I2C.
//
// Wiring:
//   GPIO6 → SDA
//   GPIO7 → SCL
//   3.3V  → VCC
//   GND   → GND
//   I2C address: 0x3C (most modules) or 0x3D (check your module)
//
// Dependencies in Cargo.toml:
//   ssd1306    = { version = "0.9", features = ["async"] }
//   embedded-graphics = { version = "0.8" }

use core::fmt::Write;

use embassy_rp::i2c::{self, I2c, InterruptHandler};
use embassy_rp::peripherals::{I2C0, PIN_6, PIN_7};
use embassy_rp::bind_interrupts;
use embassy_time::{Duration, Timer};

use embedded_graphics::{
    mono_font::{
        ascii::{FONT_6X10, FONT_6X12, FONT_9X15_BOLD},
        MonoTextStyle,
        MonoTextStyleBuilder,
    },
    pixelcolor::BinaryColor,
    prelude::*,
    primitives::{
        Line, PrimitiveStyle, Rectangle,
    },
    text::{Baseline, Text, TextStyleBuilder},
};

use heapless::String;
use ssd1306::{
    mode::BufferedGraphicsMode,
    prelude::*,
    rotation::DisplayRotation,
    size::DisplaySize128x64,
    I2CDisplayInterface,
    Ssd1306,
};

use defmt::*;

use crate::SensorState;
use crate::STATE;

// ── Type aliases ───────────────────────────────────────────────────────────
// The SSD1306 driver type is deeply generic — alias it so function
// signatures stay readable. This is a common Rust embedded pattern.

type I2cBus    = I2c<'static, I2C0, i2c::Async>;
type OledDisplay = Ssd1306<
    I2CInterface<I2cBus>,
    DisplaySize128x64,
    BufferedGraphicsMode<DisplaySize128x64>,
>;

// ── Text styles ────────────────────────────────────────────────────────────
// Define once, reuse everywhere.
// BinaryColor::On  = white pixel (OLED lit)
// BinaryColor::Off = black pixel (OLED dark)

fn style_normal() -> MonoTextStyle<'static, BinaryColor> {
    MonoTextStyleBuilder::new()
        .font(&FONT_6X10)
        .text_color(BinaryColor::On)
        .build()
}

fn style_bold() -> MonoTextStyle<'static, BinaryColor> {
    MonoTextStyleBuilder::new()
        .font(&FONT_9X15_BOLD)
        .text_color(BinaryColor::On)
        .build()
}

fn style_small() -> MonoTextStyle<'static, BinaryColor> {
    MonoTextStyleBuilder::new()
        .font(&FONT_6X10)
        .text_color(BinaryColor::On)
        .build()
}

fn style_inverted() -> MonoTextStyle<'static, BinaryColor> {
    MonoTextStyleBuilder::new()
        .font(&FONT_6X10)
        .text_color(BinaryColor::Off)
        .background_color(BinaryColor::On)
        .build()
}

// ── Layout constants ───────────────────────────────────────────────────────
// 128 x 64 pixel display
// FONT_6X10:      6px wide, 10px tall — fits 21 chars × 6 rows
// FONT_9X15_BOLD: 9px wide, 15px tall — fits 14 chars × 4 rows

const SCREEN_W: i32 = 128;
const SCREEN_H: i32 = 64;

// Row Y positions for FONT_6X10
const ROW_0: i32 =  0;   // top — title bar
const ROW_1: i32 = 11;
const ROW_2: i32 = 22;
const ROW_3: i32 = 33;
const ROW_4: i32 = 44;
const ROW_5: i32 = 54;   // bottom status line

// ── Display pages ──────────────────────────────────────────────────────────
// We rotate between two pages so all sensor data fits on the small screen.
// Page 0: water, temperature, humidity, alarm status
// Page 1: motion, CO, IP address, uptime

#[derive(Clone, Copy, PartialEq)]
enum Page {
    Sensors,   // page 0
    Status,    // page 1
}

impl Page {
    fn next(self) -> Self {
        match self {
            Page::Sensors => Page::Status,
            Page::Status  => Page::Sensors,
        }
    }
}

// ── OLED task ──────────────────────────────────────────────────────────────

#[embassy_executor::task]
pub async fn oled_task(
    i2c_peripheral: I2C0,
    sda: PIN_6,
    scl: PIN_7,
    irqs: crate::Irqs,
) {
    // ── Initialize I2C bus ─────────────────────────────────────────────
    // 400kHz "fast mode" — standard for SSD1306
    let i2c = I2c::new_async(
        i2c_peripheral,
        scl,
        sda,
        irqs,
        i2c::Config::default(),
    );

    // ── Initialize SSD1306 ─────────────────────────────────────────────
    let interface = I2CDisplayInterface::new(i2c);

    let mut display = Ssd1306::new(
        interface,
        DisplaySize128x64,
        DisplayRotation::Rotate0,
    )
    .into_buffered_graphics_mode();

    // init() sends the initialization command sequence to the OLED.
    // If this fails the display is likely wired incorrectly or the
    // I2C address is wrong (try 0x3D if 0x3C doesn't work).
    match display.init() {
        Ok(_)  => info!("OLED initialized"),
        Err(e) => {
            error!("OLED init failed — check wiring and I2C address");
            // Don't panic — the rest of the system works without the display.
            // Return early from this task only; other tasks continue.
            return;
        }
    }

    display.clear(BinaryColor::Off).ok();
    display.flush().ok();

    // Show a startup splash for 2 seconds
    draw_splash(&mut display);
    display.flush().ok();
    Timer::after(Duration::from_secs(2)).await;

    // ── Main display loop ──────────────────────────────────────────────
    let mut page        = Page::Sensors;
    let mut page_ticks  = 0u32;
    let mut tick        = 0u32;

    // Page rotation: switch every 5 seconds (50 × 100ms ticks)
    const PAGE_TICKS: u32 = 50;

    loop {
        // Snapshot state — hold the lock as briefly as possible
        let s = {
            let state = STATE.lock().await;
            state.clone()
        };

        // Clear framebuffer
        display.clear(BinaryColor::Off).ok();

        // Draw current page
        match page {
            Page::Sensors => draw_sensors_page(&mut display, &s, tick),
            Page::Status  => draw_status_page(&mut display, &s),
        }

        // Flush framebuffer to display over I2C
        // This sends 1024 bytes (128×64 / 8) — takes ~2ms at 400kHz
        display.flush().ok();

        // Rotate page every PAGE_TICKS iterations
        page_ticks += 1;
        if page_ticks >= PAGE_TICKS {
            page_ticks = 0;
            page = page.next();
        }

        tick = tick.wrapping_add(1);

        // Refresh every 100ms — smooth enough, doesn't hammer I2C
        Timer::after(Duration::from_millis(100)).await;
    }
}

// ── Page renderers ─────────────────────────────────────────────────────────

// Splash screen shown at startup
fn draw_splash(display: &mut OledDisplay) {
    let title_style = MonoTextStyleBuilder::new()
        .font(&FONT_9X15_BOLD)
        .text_color(BinaryColor::On)
        .build();

    let sub_style = style_normal();

    Text::with_baseline(
        "Basement",
        Point::new(16, 10),
        title_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();

    Text::with_baseline(
        "Monitor",
        Point::new(25, 28),
        title_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // Horizontal divider
    Line::new(Point::new(0, 47), Point::new(127, 47))
        .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
        .draw(display)
        .ok();

    Text::with_baseline(
        "Rust + Embassy",
        Point::new(14, 52),
        sub_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();
}

// Page 0: primary sensor readings
//
// ┌────────────────────────┐
// │ BASEMENT MONITOR       │  ← inverted title bar
// │ Water: DRY             │  ← or "!! WET !!" when triggered
// │ Temp:  21.5 C          │
// │ Humid: 62.0 %          │
// │ Alarm: OFF             │  ← or "ACTIVE" inverted when triggered
// │ [========   ] 1/2      │  ← page indicator
// └────────────────────────┘

fn draw_sensors_page(display: &mut OledDisplay, s: &SensorState, tick: u32) {
    // ── Title bar (inverted) ───────────────────────────────────────────
    Rectangle::new(Point::new(0, 0), Size::new(128, 11))
        .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
        .draw(display)
        .ok();

    Text::with_baseline(
        "BASEMENT MONITOR",
        Point::new(2, ROW_0),
        style_inverted(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── Water status ───────────────────────────────────────────────────
    if s.water_detected {
        // Flashing alert — invert every other tick (every 100ms)
        if tick % 2 == 0 {
            Rectangle::new(Point::new(0, ROW_1), Size::new(128, 11))
                .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
                .draw(display)
                .ok();
            Text::with_baseline(
                "Water: !! WET !!",
                Point::new(2, ROW_1),
                style_inverted(),
                Baseline::Top,
            )
            .draw(display)
            .ok();
        } else {
            Text::with_baseline(
                "Water: !! WET !!",
                Point::new(2, ROW_1),
                style_normal(),
                Baseline::Top,
            )
            .draw(display)
            .ok();
        }
    } else {
        Text::with_baseline(
            "Water: DRY",
            Point::new(2, ROW_1),
            style_normal(),
            Baseline::Top,
        )
        .draw(display)
        .ok();
    }

    // ── Temperature ────────────────────────────────────────────────────
    // heapless::String for formatting — no heap allocation
    let mut buf: String<24> = String::new();
    write!(buf, "Temp:  {:.1} C", s.temperature_c).ok();
    Text::with_baseline(
        buf.as_str(),
        Point::new(2, ROW_2),
        style_normal(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── Humidity ───────────────────────────────────────────────────────
    let mut buf: String<24> = String::new();
    write!(buf, "Humid: {:.1} %", s.humidity_pct).ok();

    // Highlight high humidity as a warning
    let hum_style = if s.humidity_pct > 85.0 {
        style_inverted()
    } else {
        style_normal()
    };

    if s.humidity_pct > 85.0 {
        Rectangle::new(Point::new(0, ROW_3), Size::new(128, 11))
            .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
            .draw(display)
            .ok();
    }

    Text::with_baseline(
        buf.as_str(),
        Point::new(2, ROW_3),
        hum_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── Alarm status ───────────────────────────────────────────────────
    if s.alarm_active {
        Rectangle::new(Point::new(0, ROW_4), Size::new(128, 11))
            .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
            .draw(display)
            .ok();
        Text::with_baseline(
            "Alarm: ACTIVE",
            Point::new(2, ROW_4),
            style_inverted(),
            Baseline::Top,
        )
        .draw(display)
        .ok();
    } else {
        Text::with_baseline(
            "Alarm: OFF",
            Point::new(2, ROW_4),
            style_normal(),
            Baseline::Top,
        )
        .draw(display)
        .ok();
    }

    // ── Page indicator ─────────────────────────────────────────────────
    draw_page_indicator(display, 0, 2);
}

// Page 1: motion, CO, network status
//
// ┌────────────────────────┐
// │ STATUS                 │  ← inverted title bar
// │ Motion: CLEAR          │
// │ CO:     12 ppm  OK     │
// │ CO:     180 ppm DANGER │  ← when elevated
// │ Net:    192.168.1.42   │
// │ [   ========] 2/2      │  ← page indicator
// └────────────────────────┘

fn draw_status_page(display: &mut OledDisplay, s: &SensorState) {
    // ── Title bar ──────────────────────────────────────────────────────
    Rectangle::new(Point::new(0, 0), Size::new(128, 11))
        .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
        .draw(display)
        .ok();

    Text::with_baseline(
        "STATUS",
        Point::new(2, ROW_0),
        style_inverted(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── Motion ─────────────────────────────────────────────────────────
    let motion_text = if s.motion_detected {
        "Motion: DETECTED"
    } else {
        "Motion: CLEAR"
    };

    Text::with_baseline(
        motion_text,
        Point::new(2, ROW_1),
        style_normal(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── CO level with severity indicator ──────────────────────────────
    let mut co_buf: String<24> = String::new();
    let co_severity = match s.co_ppm {
        0..=49   => "OK",
        50..=149  => "WARN",
        _         => "DANGER",
    };
    write!(co_buf, "CO: {} ppm {}", s.co_ppm, co_severity).ok();

    // Invert the entire row if CO is dangerous
    if s.co_ppm >= 150 {
        Rectangle::new(Point::new(0, ROW_2), Size::new(128, 11))
            .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
            .draw(display)
            .ok();
        Text::with_baseline(
            co_buf.as_str(),
            Point::new(2, ROW_2),
            style_inverted(),
            Baseline::Top,
        )
        .draw(display)
        .ok();
    } else {
        Text::with_baseline(
            co_buf.as_str(),
            Point::new(2, ROW_2),
            style_normal(),
            Baseline::Top,
        )
        .draw(display)
        .ok();
    }

    // ── CO bar graph ───────────────────────────────────────────────────
    // Visual bar showing CO level from 0 to 300 ppm
    // max bar width = 124px (2px margin each side)
    let max_ppm: u32 = 300;
    let bar_width = ((s.co_ppm as u32).min(max_ppm) * 124 / max_ppm) as i32;

    // Background (empty bar outline)
    Rectangle::new(Point::new(2, ROW_3), Size::new(124, 8))
        .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
        .draw(display)
        .ok();

    // Fill bar
    if bar_width > 0 {
        Rectangle::new(Point::new(2, ROW_3), Size::new(bar_width as u32, 8))
            .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
            .draw(display)
            .ok();
    }

    // ── Network / IP ───────────────────────────────────────────────────
    // In a full implementation, pass the IP string into this function.
    // Shown here as a static placeholder — replace with actual IP from
    // wifi::get_ip() stored in SensorState or a separate static.
    Text::with_baseline(
        "Net: 192.168.1.x",
        Point::new(2, ROW_4),
        style_small(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // ── Page indicator ─────────────────────────────────────────────────
    draw_page_indicator(display, 1, 2);
}

// ── Shared UI widgets ──────────────────────────────────────────────────────

// Page indicator dots at the bottom of the screen.
// current_page: 0-indexed current page
// total_pages:  total number of pages
//
// Renders two dots:  ● ○  (page 0)  or  ○ ●  (page 1)
// Positioned at the bottom-right corner.

fn draw_page_indicator(display: &mut OledDisplay, current_page: u8, total_pages: u8) {
    let dot_spacing = 8i32;
    let dot_size    = 4u32;

    // Start x so dots are right-aligned with 4px margin
    let start_x = SCREEN_W - (total_pages as i32 * dot_spacing) - 4;
    let y       = SCREEN_H - 6;

    for i in 0..total_pages {
        let x = start_x + i as i32 * dot_spacing;
        let style = if i == current_page {
            PrimitiveStyle::with_fill(BinaryColor::On)   // filled = current
        } else {
            PrimitiveStyle::with_stroke(BinaryColor::On, 1) // outline = other
        };

        Rectangle::new(
            Point::new(x, y),
            Size::new(dot_size, dot_size),
        )
        .into_styled(style)
        .draw(display)
        .ok();
    }
}

// ── Display error screen ───────────────────────────────────────────────────
// Called from other tasks if they want to show a full-screen error.
// Not async — takes a pre-initialized display reference.

pub fn draw_error(display: &mut OledDisplay, message: &str) {
    display.clear(BinaryColor::Off).ok();

    // Full screen inverted error box
    Rectangle::new(Point::new(0, 0), Size::new(128, 64))
        .into_styled(PrimitiveStyle::with_fill(BinaryColor::On))
        .draw(display)
        .ok();

    Text::with_baseline(
        "ERROR",
        Point::new(40, 8),
        MonoTextStyleBuilder::new()
            .font(&FONT_9X15_BOLD)
            .text_color(BinaryColor::Off)
            .build(),
        Baseline::Top,
    )
    .draw(display)
    .ok();

    // Word-wrap message across two lines (max 21 chars each at FONT_6X10)
    let chars: heapless::Vec<char, 42> = message.chars().collect();
    let line1: String<22> = chars.iter().take(21).collect();
    let line2: String<22> = chars.iter().skip(21).take(21).collect();

    let err_text_style = MonoTextStyleBuilder::new()
        .font(&FONT_6X10)
        .text_color(BinaryColor::Off)
        .build();

    Text::with_baseline(
        line1.as_str(),
        Point::new(2, 28),
        err_text_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();

    Text::with_baseline(
        line2.as_str(),
        Point::new(2, 40),
        err_text_style,
        Baseline::Top,
    )
    .draw(display)
    .ok();

    display.flush().ok();
}

Each of the displays have their comparisons.

Dimension	C	TinyGo	Rust/Embassy
Lines of code	~520	~380	~420
External dependencies	None beyond Pico SDK	`tinygo/x/drivers/ssd1306`, `tinygo/x/tinyfont`	`ssd1306`, `embedded-graphics`
Font handling	Hand-embedded 96-char 6×8 lookup table in source	`tinyfont` package — `freemono.Regular7pt7b`	`embedded-graphics` `FONT_6X10`, `FONT_9X15_BOLD`
Framebuffer ownership	Manual `uint8_t g_framebuffer[8][128]` — global, unprotected	Managed internally by `ssd1306.Device`	Managed internally by `Ssd1306` in `BufferedGraphicsMode`
String formatting	`snprintf()` into stack `char[]` — zero allocation	`fmt.Sprintf()` — heap allocates, triggers GC	`write!(heapless::String<N>, ...)` — zero allocation
Overflow protection	None — `char[24]` silently truncates or corrupts	None at formatting layer — GC handles heap	Compile-time — `heapless::String<24>` returns `Err` if exceeded
Rectangle drawing	`fb_fill_rect()` — hand-rolled nested loop over framebuffer	`fillRect()` — wrapper over `d.SetPixel()` loop	`Rectangle::new().into_styled().draw()` — embedded-graphics primitive
Text rendering	`fb_draw_char()` — manual font table lookup + bit shifting	`tinyfont.WriteLine()` — library handles glyph lookup	`Text::with_baseline()` — embedded-graphics handles glyph lookup
Inverted text	XOR font byte with `0xFF` before writing to framebuffer	Fill background rect first, then draw foreground glyphs	`MonoTextStyleBuilder` sets `text_color` + `background_color`
I2C peripheral safety	Convention only — nothing prevents two functions using I2C	Convention only — goroutine owns display by discipline	Compiler-enforced — `I2C0` peripheral moved into task, unusable elsewhere
Flush to display	`ssd1306_flush_all()` — manual I2C command sequence + data	`display.Display()` — driver handles command sequence	`display.flush()` — driver handles command sequence
Init sequence	17 raw command bytes hand-coded against datasheet	Driver handles init internally in `display.Configure()`	Driver handles init internally in `display.init()`
Error screen	`display_error()` — inverted box + `strncpy` word wrap	`DrawError()` — inverted box + rune slice word wrap	`draw_error()` — inverted box + `heapless::Vec<char>` word wrap
Page rotation	`static` local variables track tick count and current page	Local variables in goroutine stack — naturally scoped	Local variables in async task stack — naturally scoped
Flashing water alert	`tick % 2 == 0` on `uint32_t g_tick` global	`tick % 2 == 0` on `uint32` goroutine-local	`tick % 2 == 0` on `u32` task-local
Bar graph	`fb_draw_bar()` — outline loop + fill rect against framebuffer	`drawBarGraph()` — outline loop + `fillRect()` wrapper	`Rectangle` primitives from embedded-graphics
Page indicator dots	`fb_draw_page_indicator()` — filled vs outline rect manually	`drawPageIndicator()` — filled vs outline rect via SetPixel	`Rectangle` with `PrimitiveStyle::with_fill` vs `with_stroke`
Splash screen	`display_draw_splash()` — 2s blocking `sleep_ms()`	`drawSplash()` — 2s `time.Sleep()`, other goroutines run	`draw_splash()` — 2s `Timer::after().await`, other tasks run
Heap allocation	Zero	Yes — `fmt.Sprintf()` on every refresh	Zero
GC pressure	None (no GC)	Moderate — 6 `fmt.Sprintf()` calls per 100ms refresh	None (no GC)
Binary contribution	Smallest — font table is 576 bytes of const data	Medium — pulls in tinyfont + ssd1306 driver	Small — embedded-graphics is heavily inlined by LLVM
Concurrency safety	`display_poll()` called from main loop — single-threaded by structure	Goroutine owns display — safe by scheduler convention	Peripheral ownership proven at compile time — safe by construction
Readability of page layout	Low — pixel coordinates scattered across `fb_draw_*` calls	High — sequential `drawString()` calls read like a template	High — `Text::with_baseline()` calls read like a template
Readability of primitives	Low — manual bit manipulation in `fb_set_pixel()`	Medium — `SetPixel()` loop is clear but verbose	High — `Rectangle`, `Line` primitives are self-documenting
Debuggability	`printf()` to USB serial — no display state introspection	`println!()` to USB serial — goroutine stack visible in panic	`defmt::info!()` via RTT — structured logging, timestamps, log levels
Portability to another MCU	Rewrite I2C calls and init sequence	Change `machine.I2C0` target — driver abstracts hardware	Change `embassy-rp` to `embassy-stm32` — HAL abstracts hardware
Time to first pixel	Longest — write init sequence, font table, framebuffer	Shortest — `go get` + 4 lines to configure	Medium — `Cargo.toml` deps + type plumbing

C requires the most work here and it shows. The 6×8 font table
is 576 bytes of hand-curated hex values embedded directly in display.c.
Every character is 6 bytes — one byte per column of pixels, bit 0 at
the top. Rendering a character means indexing into this table, iterating
6 columns × 8 rows, and calling fb_set_pixel() for each. Inversion
means XOR-ing each column byte with 0xFF before rendering. This is
the same technique every SSD1306 driver written in C uses — it is proven
and correct, but you wrote it, you own it, and you debug it when it
breaks.

TinyGo delegates to tinyfont.WriteLine() with
freemono.Regular7pt7b. The font data lives in the tinyfont package.
Inversion requires drawing a filled background rectangle before the
glyphs, because tinyfont does not have a background color parameter.
This is a minor awkwardness — two calls instead of one — but the font
rendering itself is entirely handled by the library.

Rust uses embedded-graphics MonoTextStyleBuilder which accepts
both text_color and background_color as first-class parameters.
Inversion is MonoTextStyleBuilder::new().text_color(Off).background_color(On).build().
One style object, passed to Text::with_baseline(). No manual rectangle.
No XOR. The library handles glyph lookup, background fill, and pixel
writing in a single pass.

Winner: Rust — inversion is a style parameter, not a manual
pre-drawing step. Font selection is a type, not a hex table. The
embedded-graphics abstraction is the most expressive of the three.

Alarm Implementation

Alarm sources:
  Water detected   → CRITICAL  → fast pulse (200ms on / 200ms off)
                               → relay activates
                               → requires manual acknowledge
  CO ≥ 150ppm      → CRITICAL  → fast pulse
                               → relay activates
                               → requires manual acknowledge
  CO 50-149ppm     → WARNING   → slow pulse (800ms on / 800ms off)
                               → relay stays off
                               → auto-clears when CO drops
  Humidity > 85%   → ADVISORY  → single beep every 30s
                               → relay stays off
                               → auto-clears

Acknowledge:
  HTTP POST /alarm/acknowledge clears latched alarms
  Physical button on GPIO10 also acknowledges

Relay:
  Activates on CRITICAL only
  Stays active until acknowledged even if sensor clears
  Deactivates on acknowledge

Go `alarm/alarm.go` Implementation

// alarm/alarm.go
//
// Alarm management for the basement monitor.
// Identical severity model to alarm.c and alarm.rs.
//
// TinyGo structural position:
//   More readable than C — pulse loop uses time.Sleep() not timestamps.
//   Less safe than Rust — pin ownership is by convention not compiler.
//   Goroutine-local latch state — cleaner than C's globals,
//   less explicit than Rust's task-local variables in the type system.

package alarm

import (
    "basement-monitor/sensors"
    "machine"
    "time"
)

// ── Severity levels ────────────────────────────────────────────────────────
// Same four levels as C's AlarmLevel enum and Rust's AlarmLevel enum.
// Go has no enum keyword — iota gives us the same ordered constants.

type alarmLevel uint8

const (
    levelNone     alarmLevel = iota // 0
    levelAdvisory                   // 1
    levelWarning                    // 2
    levelCritical                   // 3
)

func (l alarmLevel) String() string {
    switch l {
    case levelNone:     return "NONE"
    case levelAdvisory: return "ADVISORY"
    case levelWarning:  return "WARNING"
    case levelCritical: return "CRITICAL"
    default:            return "UNKNOWN"
    }
}

// ── Pulse durations ────────────────────────────────────────────────────────

const (
    criticalOn       = 200 * time.Millisecond
    criticalOff      = 200 * time.Millisecond
    warningOn        = 800 * time.Millisecond
    warningOff       = 800 * time.Millisecond
    advisoryBeep     = 100 * time.Millisecond
    advisoryInterval = 30 * time.Second
    idlePoll         = 100 * time.Millisecond
)

// ── Acknowledge channel ────────────────────────────────────────────────────
// HTTP handler and button goroutine send on this channel to trigger
// acknowledgement inside AlarmTask without sharing any mutable state.
// This is idiomatic Go/TinyGo — communicate by channel, not shared memory.
// C equivalent: alarm_acknowledge() writes directly to g_alarm.
// Rust equivalent: a separate channel or atomic flag (no channel needed
// because acknowledge() is called inside the same async task).

var AckChan = make(chan struct{}, 1)

// Acknowledge signals the alarm task to clear latched alarms.
// Safe to call from any goroutine — the HTTP handler calls this.
func Acknowledge() {
    select {
    case AckChan <- struct{}{}:
    default:
        // Channel full — ack already pending, that's fine
    }
}

// ── AlarmTask ──────────────────────────────────────────────────────────────

// AlarmTask runs as a goroutine, managing buzzer and relay based on
// sensor state severity. Reads sensor state via getState snapshot
// function — same pattern as display/oled.go and alarm.rs.

func AlarmTask(
    buzzerPin machine.Pin,
    relayPin  machine.Pin,
    ackPin    machine.Pin,
    getState  func() sensors.SensorState,
    setState  func(func(*sensors.SensorState)),
) {
    // Configure pins
    buzzerPin.Configure(machine.PinConfig{Mode: machine.PinOutput})
    relayPin.Configure(machine.PinConfig{Mode: machine.PinOutput})
    ackPin.Configure(machine.PinConfig{Mode: machine.PinInputPullup}) // active LOW

    buzzerPin.Low()
    relayPin.Low()

    println("[ALARM] Initialized")

    // ── Goroutine-local latch state ────────────────────────────────────
    // Lives on this goroutine's stack — no mutex needed.
    // This is the cleanest of the three implementations for latch state:
    //   C:    g_alarm global struct — anything can corrupt it
    //   Rust: task-local variables — compiler proves exclusivity
    //   TinyGo: goroutine-local vars — safe by scheduler convention
    var (
        waterLatched    bool
        coCritLatched   bool
        currentLevel    alarmLevel
        triggerTime     time.Time
    )

    // Start button monitor goroutine — sends on AckChan when pressed
    go buttonMonitor(ackPin)

    for {
        s := getState()

        // ── Check for acknowledge ──────────────────────────────────────
        select {
        case <-AckChan:
            currentLevel = acknowledge(
                buzzerPin, relayPin,
                &waterLatched, &coCritLatched,
                s, triggerTime, setState,
            )
            continue
        default:
            // No ack pending — continue
        }

        // ── Compute severity ───────────────────────────────────────────
        liveLevel := computeLevel(s)

        // ── Update latches ─────────────────────────────────────────────
        if liveLevel == levelCritical {
            if s.WaterDetected { waterLatched  = true }
            if s.CoPpm >= 150  { coCritLatched = true }

            if currentLevel != levelCritical {
                triggerTime = time.Now()
                println("[ALARM] CRITICAL — water:", s.WaterDetected,
                    "co:", s.CoPpm, "ppm")
            }
        }

        effective := liveLevel
        if waterLatched || coCritLatched {
            if effective < levelCritical {
                effective = levelCritical
            }
        }

        if effective != currentLevel {
            println("[ALARM] Level:", currentLevel.String(),
                "→", effective.String())
            currentLevel = effective
        }

        // ── Update shared state ────────────────────────────────────────
        setState(func(st *sensors.SensorState) {
            st.AlarmActive = effective > levelNone
        })

        // ── Drive relay ────────────────────────────────────────────────
        if effective == levelCritical {
            if !relayPin.Get() {
                relayPin.High()
                println("[ALARM] Relay ON")
            }
        } else {
            if relayPin.Get() {
                relayPin.Low()
                println("[ALARM] Relay OFF")
            }
        }

        // ── Drive buzzer ───────────────────────────────────────────────
        // This is TinyGo's clearest advantage over C in this file.
        // time.Sleep() yields the goroutine — other goroutines run
        // during the on/off intervals. The pulse loop reads linearly,
        // exactly matching the intended behavior.
        // C's poll_pulse() achieves the same result through timestamp
        // checking across multiple poll() calls — much harder to read.
        switch effective {
        case levelCritical:
            buzzerPin.High()
            time.Sleep(criticalOn)
            buzzerPin.Low()
            time.Sleep(criticalOff)

        case levelWarning:
            buzzerPin.High()
            time.Sleep(warningOn)
            buzzerPin.Low()
            time.Sleep(warningOff)

        case levelAdvisory:
            // Single short beep then long wait
            buzzerPin.High()
            time.Sleep(advisoryBeep)
            buzzerPin.Low()
            time.Sleep(advisoryInterval)

        case levelNone:
            buzzerPin.Low()
            relayPin.Low()
            time.Sleep(idlePoll)
        }
    }
}

// ── Button monitor ─────────────────────────────────────────────────────────
// Runs as a sub-goroutine — polls the physical button and sends
// on AckChan when pressed. Separating this from AlarmTask means
// the button can interrupt long advisory sleeps cleanly.
// C equivalent: gpio_get(PIN_ACK_BUTTON) polled inside alarm_poll().
// Rust equivalent: ack.get_level() == Level::Low checked in the task loop.

func buttonMonitor(pin machine.Pin) {
    var lastState bool = true // pull-up means HIGH = not pressed

    for {
        pressed := !pin.Get() // active LOW

        if pressed && !lastState {
            // Falling edge — button just pressed
            Acknowledge()
        }
        lastState = pressed

        time.Sleep(50 * time.Millisecond) // debounce interval
    }
}

// ── Acknowledge ────────────────────────────────────────────────────────────
// Returns the post-acknowledge alarm level so the caller can update
// currentLevel without needing a pointer to it.
// C equivalent: alarm_acknowledge() — modifies g_alarm directly.
// Rust equivalent: acknowledge() async fn called inside alarm_task.

func acknowledge(
    buzzerPin    machine.Pin,
    relayPin     machine.Pin,
    waterLatched *bool,
    coCritLatched *bool,
    s            sensors.SensorState,
    triggerTime  time.Time,
    setState     func(func(*sensors.SensorState)),
) alarmLevel {
    elapsed := time.Since(triggerTime)
    println("[ALARM] Acknowledged — active for", elapsed.Milliseconds(), "ms")

    *waterLatched   = false
    *coCritLatched  = false

    postLevel := computeLevel(s)

    setState(func(st *sensors.SensorState) {
        st.AlarmActive = postLevel > levelNone
    })

    if postLevel < levelCritical {
        relayPin.Low()
        println("[ALARM] Relay OFF (post-ack)")
    }

    buzzerPin.Low()

    println("[ALARM] Post-ack level:", postLevel.String())
    return postLevel
}

// ── Level computation ──────────────────────────────────────────────────────
// Pure function — identical priority order to C and Rust.
// Go's switch with no expression is cleaner than C's if-else chain
// and equivalent to Rust's match.

func computeLevel(s sensors.SensorState) alarmLevel {
    switch {
    case s.WaterDetected || s.CoPpm >= 150:
        return levelCritical
    case s.CoPpm >= 50:
        return levelWarning
    case s.HumidityPct > 85.0:
        return levelAdvisory
    default:
        return levelNone
    }
}

C `alarm.h` | `alarm.c` Implementation

// alarm.h
#ifndef ALARM_H
#define ALARM_H

#include <stdint.h>
#include <stdbool.h>
#include "sensors.h"

// ── Pin assignments ────────────────────────────────────────────────────────
#define PIN_BUZZER          8
#define PIN_RELAY           4   // shared with water.c — relay driven here only
#define PIN_ACK_BUTTON      10  // physical acknowledge button, active LOW

// ── Alarm severity levels ──────────────────────────────────────────────────
// Same enum used in all three implementations for consistency.
// Rust: AlarmLevel enum in alarm.rs
// TinyGo: alarmLevel type in alarm/alarm.go

typedef enum {
    ALARM_NONE     = 0,  // all sensors nominal
    ALARM_ADVISORY = 1,  // humidity warning — single beep every 30s
    ALARM_WARNING  = 2,  // CO elevated — slow pulse, no relay
    ALARM_CRITICAL = 3,  // water or dangerous CO — fast pulse + relay
} AlarmLevel;

// ── Alarm state ────────────────────────────────────────────────────────────
// Separate from SensorState — alarm has its own latching logic.
// A CRITICAL alarm latches until acknowledged even if the sensor clears.
// This mirrors real alarm panel behavior — you need to know the event
// happened even if the water has since drained.

typedef struct {
    AlarmLevel  level;            // current computed severity
    AlarmLevel  latched_level;    // highest level since last acknowledge
    bool        water_latched;    // water was detected since last ack
    bool        co_critical_latched; // CO was critical since last ack
    bool        relay_active;     // current relay state
    uint32_t    trigger_time_ms;  // when alarm first activated
    uint32_t    last_ack_time_ms; // when alarm was last acknowledged
} AlarmState;

extern AlarmState g_alarm;

// ── Public API ─────────────────────────────────────────────────────────────
void alarm_init(void);
void alarm_poll(void);                   // call from main loop
void alarm_acknowledge(void);            // clear latched alarms
bool alarm_is_active(void);              // true if any alarm level > NONE
AlarmLevel alarm_current_level(void);    // current severity
const char *alarm_level_str(AlarmLevel level); // "NONE","ADVISORY","WARNING","CRITICAL"

#endif // ALARM_H

// alarm.c
//
// Alarm management for the basement monitor.
// Drives the buzzer and relay based on sensor state severity.
//
// Severity model:
//   CRITICAL  → water detected OR CO ≥ 150ppm
//             → fast buzzer pulse (200ms/200ms)
//             → relay ON (cuts power to basement appliances)
//             → latches until acknowledged
//   WARNING   → CO 50-149ppm
//             → slow buzzer pulse (800ms/800ms)
//             → relay OFF
//             → auto-clears when CO drops below 50
//   ADVISORY  → humidity > 85%
//             → single beep every 30 seconds
//             → relay OFF
//             → auto-clears when humidity normalizes
//   NONE      → all clear, buzzer and relay off
//
// Architecture note vs Rust and TinyGo:
//   All three implement identical severity logic and state machine.
//   C uses static locals + timestamp polling from the main loop.
//   Rust uses an async task with Timer::after().await per state.
//   TinyGo uses a goroutine with time.Sleep() per state.
//   The C version is the only one that cannot sleep between states —
//   it must return from alarm_poll() immediately and check timestamps
//   on the next call. This makes the pulse timing logic more complex
//   than the Rust and TinyGo equivalents.

#include "alarm.h"
#include "sensors.h"
#include "hardware/gpio.h"
#include "pico/stdlib.h"
#include "pico/critical_section.h"
#include <stdio.h>
#include <string.h>

// ── Global alarm state ─────────────────────────────────────────────────────
AlarmState g_alarm = {
    .level               = ALARM_NONE,
    .latched_level       = ALARM_NONE,
    .water_latched       = false,
    .co_critical_latched = false,
    .relay_active        = false,
    .trigger_time_ms     = 0,
    .last_ack_time_ms    = 0,
};

// ── Pulse timing state ─────────────────────────────────────────────────────
// Because alarm_poll() must return immediately, we track buzzer toggle
// timestamps manually. This is the most structurally awkward part of
// the C implementation — compare to Rust and TinyGo where the pulse
// loop is a simple:
//   buzzer.set_high(); Timer::after(on_ms).await;
//   buzzer.set_low();  Timer::after(off_ms).await;

static bool     g_buzzer_on          = false;
static uint32_t g_next_toggle_ms     = 0;
static uint32_t g_next_advisory_ms   = 0;
static bool     g_advisory_beep_on   = false;
static uint32_t g_advisory_beep_end  = 0;

// Pulse durations in milliseconds per severity level
#define CRITICAL_ON_MS      200
#define CRITICAL_OFF_MS     200
#define WARNING_ON_MS       800
#define WARNING_OFF_MS      800
#define ADVISORY_BEEP_MS    100   // single short beep
#define ADVISORY_INTERVAL_MS 30000 // every 30 seconds

// ── Helpers ────────────────────────────────────────────────────────────────

static void buzzer_set(bool on) {
    gpio_put(PIN_BUZZER, on ? 1 : 0);
    g_buzzer_on = on;
}

static void relay_set(bool on) {
    gpio_put(PIN_RELAY, on ? 1 : 0);
    g_alarm.relay_active = on;
    if (on) {
        printf("[ALARM] Relay ACTIVATED\n");
    } else {
        printf("[ALARM] Relay DEACTIVATED\n");
    }
}

// Compute the current alarm level from sensor state.
// Does NOT latch — latching is handled in alarm_poll().
// Pure function: same inputs always produce same output.
// Rust equivalent: fn compute_level(s: &SensorState) -> AlarmLevel
// TinyGo equivalent: func computeLevel(s sensors.SensorState) alarmLevel
static AlarmLevel compute_level(const SensorState *s) {
    // CRITICAL takes priority — check first
    if (s->water_detected || s->co_ppm >= 150) {
        return ALARM_CRITICAL;
    }
    // WARNING next
    if (s->co_ppm >= 50) {
        return ALARM_WARNING;
    }
    // ADVISORY last
    if (s->humidity_pct > 85.0f) {
        return ALARM_ADVISORY;
    }
    return ALARM_NONE;
}

// ── Pulse state machine ────────────────────────────────────────────────────
// Called from alarm_poll() with the current timestamp.
// Implements the buzzer pattern for CRITICAL and WARNING levels.
// This is the timestamp-polling equivalent of:
//   loop {
//       buzzer.set_high(); Timer::after(on_ms).await;
//       buzzer.set_low();  Timer::after(off_ms).await;
//   }

static void poll_pulse(uint32_t now, uint32_t on_ms, uint32_t off_ms) {
    if (now < g_next_toggle_ms) return;  // not time yet

    if (g_buzzer_on) {
        // Currently on — turn off, schedule next on
        buzzer_set(false);
        g_next_toggle_ms = now + off_ms;
    } else {
        // Currently off — turn on, schedule next off
        buzzer_set(true);
        g_next_toggle_ms = now + on_ms;
    }
}

// Advisory beep: single short beep every 30 seconds.
// Two-phase: fire the beep, then wait for the 100ms beep to end,
// then wait 30 seconds before the next one.
static void poll_advisory(uint32_t now) {
    if (g_advisory_beep_on) {
        // Beep is active — check if it should end
        if (now >= g_advisory_beep_end) {
            buzzer_set(false);
            g_advisory_beep_on  = false;
            g_next_advisory_ms  = now + ADVISORY_INTERVAL_MS;
        }
    } else {
        // Waiting for next beep interval
        if (now >= g_next_advisory_ms) {
            buzzer_set(true);
            g_advisory_beep_on  = true;
            g_advisory_beep_end = now + ADVISORY_BEEP_MS;
        }
    }
}

// ── Public API ─────────────────────────────────────────────────────────────

void alarm_init(void) {
    gpio_init(PIN_BUZZER);
    gpio_set_dir(PIN_BUZZER, GPIO_OUT);
    gpio_put(PIN_BUZZER, 0);

    gpio_init(PIN_RELAY);
    gpio_set_dir(PIN_RELAY, GPIO_OUT);
    gpio_put(PIN_RELAY, 0);

    gpio_init(PIN_ACK_BUTTON);
    gpio_set_dir(PIN_ACK_BUTTON, GPIO_IN);
    gpio_pull_up(PIN_ACK_BUTTON);  // active LOW — button pulls to GND

    printf("[ALARM] Initialized — buzzer=GPIO%d relay=GPIO%d ack=GPIO%d\n",
           PIN_BUZZER, PIN_RELAY, PIN_ACK_BUTTON);
}

void alarm_poll(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    // ── Check physical acknowledge button ──────────────────────────────
    // Active LOW — button connects GPIO10 to GND when pressed.
    // Debounced by checking on every poll cycle (every ~100µs in main
    // loop) — in practice the button press lasts many milliseconds so
    // a single poll is sufficient. A production implementation would
    // track the falling edge rather than level.
    if (!gpio_get(PIN_ACK_BUTTON)) {
        alarm_acknowledge();
    }

    // ── Snapshot sensor state ──────────────────────────────────────────
    state_lock();
    SensorState s = g_state;
    state_unlock();

    // ── Compute current severity ───────────────────────────────────────
    AlarmLevel current = compute_level(&s);

    // ── Latch critical events ──────────────────────────────────────────
    // CRITICAL alarms latch — they stay active even if the sensor clears.
    // This ensures a flood event is visible even after water drains.
    // WARNING and ADVISORY do not latch — they auto-clear.
    if (current == ALARM_CRITICAL) {
        if (s.water_detected)  g_alarm.water_latched       = true;
        if (s.co_ppm >= 150)   g_alarm.co_critical_latched = true;

        if (g_alarm.level != ALARM_CRITICAL) {
            // Transition to CRITICAL
            g_alarm.trigger_time_ms = now;
            printf("[ALARM] CRITICAL — water=%s co=%uppm\n",
                   s.water_detected ? "YES" : "NO", s.co_ppm);
        }
    }

    // Effective level accounts for latching:
    // if we were CRITICAL and it latched, we stay CRITICAL until ack
    AlarmLevel effective = current;
    if (g_alarm.water_latched || g_alarm.co_critical_latched) {
        if (effective < ALARM_CRITICAL) {
            effective = ALARM_CRITICAL;
        }
    }

    // Track level transitions for logging
    if (effective != g_alarm.level) {
        printf("[ALARM] Level: %s → %s\n",
               alarm_level_str(g_alarm.level),
               alarm_level_str(effective));
        g_alarm.level = effective;

        // Reset pulse timing on level change
        g_buzzer_on      = false;
        g_next_toggle_ms = now;
        buzzer_set(false);
    }

    // ── Update shared sensor state alarm flag ──────────────────────────
    bool alarm_on = (effective > ALARM_NONE);
    state_lock();
    g_state.alarm_active = alarm_on;
    state_unlock();

    // ── Drive relay ────────────────────────────────────────────────────
    // Relay activates on CRITICAL, stays on until acknowledged.
    // In Rust: relay.set_high().unwrap() inside the async task.
    // In TinyGo: relayPin.High() inside the goroutine.
    bool relay_should_be_on = (effective == ALARM_CRITICAL);
    if (relay_should_be_on != g_alarm.relay_active) {
        relay_set(relay_should_be_on);
    }

    // ── Drive buzzer ───────────────────────────────────────────────────
    switch (effective) {
        case ALARM_CRITICAL:
            poll_pulse(now, CRITICAL_ON_MS, CRITICAL_OFF_MS);
            break;

        case ALARM_WARNING:
            poll_pulse(now, WARNING_ON_MS, WARNING_OFF_MS);
            break;

        case ALARM_ADVISORY:
            poll_advisory(now);
            break;

        case ALARM_NONE:
        default:
            // Silence everything
            if (g_buzzer_on) {
                buzzer_set(false);
            }
            break;
    }
}

void alarm_acknowledge(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    if (g_alarm.latched_level == ALARM_NONE &&
        g_alarm.level         == ALARM_NONE) {
        return; // nothing to acknowledge
    }

    printf("[ALARM] Acknowledged at %lums (active for %lums)\n",
           now,
           now - g_alarm.trigger_time_ms);

    // Clear all latches
    g_alarm.water_latched       = false;
    g_alarm.co_critical_latched = false;
    g_alarm.latched_level       = ALARM_NONE;
    g_alarm.last_ack_time_ms    = now;

    // Re-evaluate from current sensor state
    state_lock();
    SensorState s = g_state;
    state_unlock();

    g_alarm.level = compute_level(&s);

    // Update shared state
    state_lock();
    g_state.alarm_active = (g_alarm.level > ALARM_NONE);
    state_unlock();

    // Deactivate relay if no longer CRITICAL
    if (g_alarm.level < ALARM_CRITICAL) {
        relay_set(false);
    }

    // Stop buzzer — will restart if level is still active
    buzzer_set(false);
    g_next_toggle_ms   = 0;
    g_next_advisory_ms = 0;

    printf("[ALARM] Post-ack level: %s\n",
           alarm_level_str(g_alarm.level));
}

bool alarm_is_active(void) {
    return g_alarm.level > ALARM_NONE;
}

AlarmLevel alarm_current_level(void) {
    return g_alarm.level;
}

const char *alarm_level_str(AlarmLevel level) {
    switch (level) {
        case ALARM_NONE:     return "NONE";
        case ALARM_ADVISORY: return "ADVISORY";
        case ALARM_WARNING:  return "WARNING";
        case ALARM_CRITICAL: return "CRITICAL";
        default:             return "UNKNOWN";
    }
}

Rust `alarm.rs` Implementation

// src/alarm.rs
//
// Alarm management for the basement monitor.
// Identical severity model to alarm.c and alarm/alarm.go:
//
//   CRITICAL  → water OR CO ≥ 150ppm → fast pulse + relay + latches
//   WARNING   → CO 50-149ppm         → slow pulse, no relay, auto-clears
//   ADVISORY  → humidity > 85%       → single beep/30s, auto-clears
//   NONE      → all clear
//
// Structural advantage over C:
//   The pulse loop is a linear async state machine — no timestamp
//   polling, no static locals, no manual toggle tracking.
//   buzzer.set_high(); Timer::after(on).await;
//   buzzer.set_low();  Timer::after(off).await;
//   reads exactly like the intended behavior.
//
// Structural advantage over TinyGo:
//   PIN_8 (buzzer) and PIN_4 (relay) are moved into this task.
//   The compiler proves no other task can drive them simultaneously.
//   In TinyGo, pin ownership is by convention.

use embassy_rp::gpio::{Input, Level, Output, Pull};
use embassy_rp::peripherals::{PIN_10, PIN_4, PIN_8};
use embassy_time::{Duration, Instant, Timer};
use defmt::*;

use crate::{SensorState, STATE};

// ── Alarm severity ─────────────────────────────────────────────────────────

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, defmt::Format)]
pub enum AlarmLevel {
    None     = 0,
    Advisory = 1,
    Warning  = 2,
    Critical = 3,
}

impl AlarmLevel {
    fn label(self) -> &'static str {
        match self {
            AlarmLevel::None     => "NONE",
            AlarmLevel::Advisory => "ADVISORY",
            AlarmLevel::Warning  => "WARNING",
            AlarmLevel::Critical => "CRITICAL",
        }
    }
}

// ── Pulse durations ────────────────────────────────────────────────────────

const CRITICAL_ON:  Duration = Duration::from_millis(200);
const CRITICAL_OFF: Duration = Duration::from_millis(200);
const WARNING_ON:   Duration = Duration::from_millis(800);
const WARNING_OFF:  Duration = Duration::from_millis(800);
const ADVISORY_BEEP: Duration = Duration::from_millis(100);
const ADVISORY_INTERVAL: Duration = Duration::from_secs(30);

// ── Alarm task ─────────────────────────────────────────────────────────────

#[embassy_executor::task]
pub async fn alarm_task(
    buzzer_pin: PIN_8,
    relay_pin:  PIN_4,
    ack_pin:    PIN_10,
) {
    let mut buzzer = Output::new(buzzer_pin, Level::Low);
    let mut relay  = Output::new(relay_pin,  Level::Low);
    let     ack    = Input::new(ack_pin, Pull::Up);  // active LOW

    // ── Latch state ────────────────────────────────────────────────────
    // Tracks which CRITICAL events have occurred since last acknowledge.
    // Local to this task — no mutex needed, no shared state.
    // This is cleaner than C's g_alarm global or TinyGo's package-level var.
    let mut water_latched    = false;
    let mut co_crit_latched  = false;
    let mut trigger_time     = Instant::now();
    let mut current_level    = AlarmLevel::None;

    info!("Alarm task started — buzzer=PIN_8 relay=PIN_4 ack=PIN_10");

    loop {
        // ── Snapshot sensor state ──────────────────────────────────────
        let s = {
            let state = STATE.lock().await;
            state.clone()
        };

        // ── Check acknowledge button ───────────────────────────────────
        // Active LOW — pressed when pin reads Low.
        // In C: gpio_get(PIN_ACK_BUTTON) == 0 in alarm_poll().
        // In TinyGo: !ackPin.Get() in the goroutine loop.
        // Here: ack.get_level() == Level::Low — same logic, typed.
        if ack.get_level() == Level::Low {
            acknowledge(
                &mut buzzer,
                &mut relay,
                &mut water_latched,
                &mut co_crit_latched,
                &mut current_level,
                &s,
                trigger_time,
            ).await;
        }

        // ── Compute severity ───────────────────────────────────────────
        let live_level = compute_level(&s);

        // ── Update latches ─────────────────────────────────────────────
        if live_level == AlarmLevel::Critical {
            if s.water_detected  { water_latched   = true; }
            if s.co_ppm >= 150   { co_crit_latched = true; }

            if current_level != AlarmLevel::Critical {
                trigger_time = Instant::now();
                warn!("CRITICAL alarm triggered — water={} co={}ppm",
                    s.water_detected, s.co_ppm);
            }
        }

        // Effective level respects latching
        let effective = if water_latched || co_crit_latched {
            AlarmLevel::Critical.max(live_level)
        } else {
            live_level
        };

        // Log level transitions
        if effective != current_level {
            info!("Alarm level: {} → {}",
                current_level.label(), effective.label());
            current_level = effective;
        }

        // ── Update shared state ────────────────────────────────────────
        {
            let mut state = STATE.lock().await;
            state.alarm_active = effective > AlarmLevel::None;
        }

        // ── Drive relay ────────────────────────────────────────────────
        match effective {
            AlarmLevel::Critical => relay.set_high(),
            _                    => relay.set_low(),
        }

        // ── Drive buzzer + timing ──────────────────────────────────────
        // This is the key structural difference from C.
        // In C: poll_pulse() checks timestamps and returns immediately.
        // Here: we await the actual duration — the task suspends,
        // Embassy runs other tasks during the wait, and we resume
        // exactly when the timer fires. Linear, readable, correct.
        match effective {
            AlarmLevel::Critical => {
                buzzer.set_high();
                Timer::after(CRITICAL_ON).await;
                buzzer.set_low();
                Timer::after(CRITICAL_OFF).await;
            }

            AlarmLevel::Warning => {
                buzzer.set_high();
                Timer::after(WARNING_ON).await;
                buzzer.set_low();
                Timer::after(WARNING_OFF).await;
            }

            AlarmLevel::Advisory => {
                // Single short beep then wait 30 seconds
                buzzer.set_high();
                Timer::after(ADVISORY_BEEP).await;
                buzzer.set_low();
                Timer::after(ADVISORY_INTERVAL).await;
            }

            AlarmLevel::None => {
                // Ensure both are off then re-check after 100ms
                buzzer.set_low();
                relay.set_low();
                Timer::after(Duration::from_millis(100)).await;
            }
        }
    }
}

// ── Acknowledge ────────────────────────────────────────────────────────────
// Extracted as an async function so it can .await the STATE lock
// without holding a non-Send reference across the await point.
// C equivalent: alarm_acknowledge() — synchronous, called directly.
// TinyGo equivalent: acknowledge() func called from the goroutine.

async fn acknowledge(
    buzzer:          &mut Output<'static>,
    relay:           &mut Output<'static>,
    water_latched:   &mut bool,
    co_crit_latched: &mut bool,
    current_level:   &mut AlarmLevel,
    s:               &SensorState,
    trigger_time:    Instant,
) {
    let elapsed = Instant::now() - trigger_time;

    info!("Alarm acknowledged — active for {}ms", elapsed.as_millis());

    *water_latched   = false;
    *co_crit_latched = false;

    // Re-evaluate from current live sensor state
    *current_level = compute_level(s);

    // Update shared state
    {
        let mut state = STATE.lock().await;
        state.alarm_active = *current_level > AlarmLevel::None;
    }

    // Deactivate hardware if no longer critical
    if *current_level < AlarmLevel::Critical {
        relay.set_low();
    }
    buzzer.set_low();

    info!("Post-ack level: {}", current_level.label());
}

// ── Level computation ──────────────────────────────────────────────────────
// Pure function — no side effects, no state mutation.
// Identical priority order to C's compute_level() and
// TinyGo's computeLevel().

fn compute_level(s: &SensorState) -> AlarmLevel {
    if s.water_detected || s.co_ppm >= 150 {
        return AlarmLevel::Critical;
    }
    if s.co_ppm >= 50 {
        return AlarmLevel::Warning;
    }
    if s.humidity_pct > 85.0 {
        return AlarmLevel::Advisory;
    }
    AlarmLevel::None
}

As you can see from this project, we have the sensors, display and now the alarm programmed. Next lets build out the wifi package.

Networking Capabilities

Responsibilities:
  Init          → configure CYW43 chip, set station mode
  Connect       → join WPA2 network with retry + backoff
  Reconnect     → detect disconnection, re-join automatically
  Status        → expose connected/disconnected/ip to other modules
  Signal        → RSSI reading for dashboard display
  IP address    → cached string for display and HTTP server
  LED           → Pico W onboard LED is on the CYW43, not GPIO
                  WiFi module owns it — blink on connect, solid when up
  Notify        → tell display module the IP after DHCP

The networking component will require us to have a connection readily available and you may not like how we have to embed the password into the hardware itself. Feel free to expand the tutorial further to add an extra layer of protection for what your needs are.

Go `wifi/wifi.go` Implementation

// wifi/wifi.go
//
// WiFi management for the basement monitor — Pico W / CYW43439.
//
// TinyGo's WiFi story as of v0.41:
//   - cyw43 driver is functional for WPA2 + TCP
//   - Wireless support matured significantly in v0.41 (April 2026)
//   - espradio package added for ESP32 boards in same release
//   - Reconnection requires manual implementation (shown below)
//   - LED is on CYW43 — same constraint as C and Rust
//
// Goroutine model advantage over C:
//   ConnectWithRetry() blocks the calling goroutine during connection
//   attempts but other goroutines (sensors, display, alarm) continue.
//   ReconnectTask() runs as a permanent background goroutine —
//   reconnection happens without touching the main goroutine at all.
//   C's wifi_poll() requires the main loop to drive reconnection.

package wifi

import (
    "basement-monitor/display"
    "machine"
    "sync"
    "time"

    "tinygo.org/x/drivers/cyw43"
)

// ── Credentials ────────────────────────────────────────────────────────────
// Set via tinygo build -ldflags="-X wifi.SSID=MyNet -X wifi.Password=pass"
// or via environment variables read in a build script.
// Never hardcode in source.
var (
    SSID     = "YourNetworkName" // override at build time
    Password = "YourPassword"    // override at build time
)

// ── Configuration ──────────────────────────────────────────────────────────
const (
    connectTimeout   = 30 * time.Second
    maxRetries       = 5
    retryBase        = 2 * time.Second
    retryMax         = 30 * time.Second
    reconnectCheck   = 5 * time.Second
)

// ── Connection state ───────────────────────────────────────────────────────
// Same four states as C's WifiState enum and Rust's WifiState enum.

type State uint8

const (
    StateIdle         State = iota
    StateConnecting
    StateConnected
    StateDisconnected
    StateFailed
)

func (s State) String() string {
    switch s {
    case StateIdle:         return "IDLE"
    case StateConnecting:   return "CONNECTING"
    case StateConnected:    return "CONNECTED"
    case StateDisconnected: return "DISCONNECTED"
    case StateFailed:       return "FAILED"
    default:                return "UNKNOWN"
    }
}

// ── Status struct ──────────────────────────────────────────────────────────

type Status struct {
    State          State
    IP             string
    RSSIdbm        int32
    ReconnectCount uint32
}

// ── Package state ──────────────────────────────────────────────────────────
// Protected by statusMu — same sync.Mutex pattern as SensorState in main.go.
// C equivalent: g_status global + critical_section.
// Rust equivalent: Mutex<CriticalSectionRawMutex, WifiStatus>.
// TinyGo: sync.Mutex — disables interrupts under the hood on Cortex-M,
// same mechanism as Rust's CriticalSectionRawMutex.

var (
    statusMu sync.Mutex
    status   Status

    // g_dev is the CYW43 device handle — used by SetLED and RSSI.
    g_dev *cyw43.Device

    // g_ip is the cached IP string read by display and HTTP modules.
    // display.SetWifiIP() is called whenever this changes.
    g_ip string = "0.0.0.0"
)

// GetStatus returns a snapshot of current WiFi status.
// Same snapshot pattern as sensors.GetState().
func GetStatus() Status {
    statusMu.Lock()
    s := status
    statusMu.Unlock()
    return s
}

// GetIP returns the current IP address string.
// Called by display/oled.go status page.
func GetIP() string {
    statusMu.Lock()
    ip := g_ip
    statusMu.Unlock()
    return ip
}

// IsConnected returns true if currently connected with a valid IP.
func IsConnected() bool {
    statusMu.Lock()
    connected := status.State == StateConnected
    statusMu.Unlock()
    return connected
}

func updateStatus(fn func(*Status)) {
    statusMu.Lock()
    fn(&status)
    statusMu.Unlock()
}

// ── LED control ────────────────────────────────────────────────────────────
// Pico W LED is on the CYW43 chip — cannot use machine.GPIO25.
// Same constraint as C's wifi_set_led() and Rust's control.gpio_set().
// Other packages must call wifi.SetLED() — they cannot drive it directly.

func SetLED(on bool) {
    if g_dev == nil {
        return
    }
    if on {
        g_dev.SetGPIO(0, true)
    } else {
        g_dev.SetGPIO(0, false)
    }
}

// ── Connect ────────────────────────────────────────────────────────────────

// Connect initializes the CYW43 and connects to the configured network.
// Returns the assigned IP address on success.
// Blocks the calling goroutine — other goroutines continue.
// Called from main.go before starting the HTTP server goroutine.
func Connect(ssid, password string) (string, error) {
    SSID     = ssid
    Password = password

    println("[WIFI ] Initializing CYW43...")

    dev, err := cyw43.New()
    if err != nil {
        return "", err
    }
    g_dev = dev

    println("[WIFI ] CYW43 initialized")
    SetLED(false) // start with LED off

    // Connect with retry + backoff
    ip, err := connectWithRetry()
    if err != nil {
        updateStatus(func(s *Status) {
            s.State = StateFailed
        })
        println("[WIFI ] All connection attempts failed")
        return "", err
    }

    // Start background reconnection goroutine
    // This is TinyGo's structural advantage over C here:
    // reconnection runs independently of the main loop forever.
    // C requires wifi_poll() to be called from main loop to reconnect.
    // Rust uses an async task — same independence, different mechanism.
    go reconnectTask()

    return ip, nil
}

// connectWithRetry attempts connection up to maxRetries times
// with exponential backoff between attempts.
func connectWithRetry() (string, error) {
    backoff := retryBase

    for attempt := 1; attempt <= maxRetries; attempt++ {
        println("[WIFI ] Attempt", attempt, "/", maxRetries)
        updateStatus(func(s *Status) { s.State = StateConnecting })
        SetLED(false)

        // Blink LED in background during attempt
        stopBlink := make(chan struct{})
        go blinkLED(500*time.Millisecond, stopBlink)

        err := g_dev.ConnectWPA2(SSID, Password)

        // Stop blink goroutine
        close(stopBlink)
        SetLED(false)

        if err == nil {
            ip := g_dev.GetIP()
            if ip == "" {
                ip = "0.0.0.0"
            }

            statusMu.Lock()
            status.State = StateConnected
            status.IP    = ip
            g_ip         = ip
            statusMu.Unlock()

            // Tell display module the new IP
            display.SetWifiIP(ip)

            SetLED(true) // solid LED = connected
            println("[WIFI ] Connected — IP:", ip)
            return ip, nil
        }

        println("[WIFI ] Attempt", attempt, "failed:", err.Error())

        if attempt < maxRetries {
            println("[WIFI ] Retrying in", backoff.Milliseconds(), "ms")

            // Slow blink during backoff
            stopBackoff := make(chan struct{})
            go blinkLED(500*time.Millisecond, stopBackoff)
            time.Sleep(backoff)
            close(stopBackoff)

            // Exponential backoff
            backoff *= 2
            if backoff > retryMax {
                backoff = retryMax
            }
        }
    }

    return "", errorStr("all connection attempts failed")
}

// ── Reconnection task ──────────────────────────────────────────────────────
// Runs forever as a background goroutine.
// Checks link status every reconnectCheck interval.
// If disconnected, reconnects automatically.
// This is TinyGo's most significant advantage over C for WiFi management:
// C must call wifi_poll() from the main loop.
// TinyGo goroutine is truly independent — runs on its own schedule.

func reconnectTask() {
    for {
        time.Sleep(reconnectCheck)

        if !IsConnected() {
            continue // already handling disconnect
        }

        // Check link status
        if !g_dev.IsConnected() {
            println("[WIFI ] Link lost — reconnecting")
            SetLED(false)

            var reconnectCount uint32
            statusMu.Lock()
            status.State = StateDisconnected
            status.IP    = "0.0.0.0"
            g_ip         = "0.0.0.0"
            status.ReconnectCount++
            reconnectCount = status.ReconnectCount
            statusMu.Unlock()

            display.SetWifiIP("0.0.0.0")

            println("[WIFI ] Reconnect attempt #", reconnectCount)

            ip, err := connectWithRetry()
            if err != nil {
                println("[WIFI ] Reconnection failed — continuing offline")
                updateStatus(func(s *Status) {
                    s.State = StateFailed
                })
            } else {
                println("[WIFI ] Reconnected — IP:", ip)
            }
        } else {
            // Still connected — update RSSI
            rssi := g_dev.GetRSSI()
            statusMu.Lock()
            status.RSSIdbm = int32(rssi)
            statusMu.Unlock()
        }
    }
}

// ── LED blink helper ───────────────────────────────────────────────────────
// Runs as a goroutine — blinks LED at the given interval until
// the stop channel is closed.
// This pattern is idiomatic TinyGo/Go for cancellable background tasks.
// C equivalent: led_blink_poll() with timestamp — non-blocking but
// requires the main loop to call it.
// Rust equivalent: loop { control.gpio_set(0,true).await; Timer::after().await }

func blinkLED(interval time.Duration, stop <-chan struct{}) {
    state := false
    for {
        select {
        case <-stop:
            SetLED(false)
            return
        default:
        }
        state = !state
        SetLED(state)
        time.Sleep(interval)
    }
}

// ── Error helper ───────────────────────────────────────────────────────────
// TinyGo supports errors via the standard error interface.
// heapless equivalent: errors are &'static str in Rust embedded.

type errorStr string

func (e errorStr) Error() string { return string(e) }

C `wifi.h` | `wifi.c` Implementation

// wifi.h
#ifndef WIFI_H
#define WIFI_H

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

// ── Credentials ────────────────────────────────────────────────────────────
// Passed via CMake target_compile_definitions in CMakeLists.txt:
//   target_compile_definitions(basement_monitor PRIVATE
//       WIFI_SSID=\"YourNetwork\"
//       WIFI_PASSWORD=\"YourPassword\"
//   )
// Never hardcode credentials in source — define them at build time.
#ifndef WIFI_SSID
#  error "WIFI_SSID must be defined at compile time"
#endif
#ifndef WIFI_PASSWORD
#  error "WIFI_PASSWORD must be defined at compile time"
#endif

// ── Configuration ──────────────────────────────────────────────────────────
#define WIFI_CONNECT_TIMEOUT_MS     30000   // 30s per attempt
#define WIFI_MAX_RETRIES            5       // attempts before giving up
#define WIFI_RETRY_BASE_MS          2000    // initial retry backoff
#define WIFI_RETRY_MAX_MS           30000   // maximum retry backoff
#define WIFI_RECONNECT_CHECK_MS     5000    // how often to check link
#define WIFI_IP_BUF_LEN             16      // "255.255.255.255\0"
#define WIFI_HOSTNAME               "basement-monitor"

// ── Connection state ───────────────────────────────────────────────────────
typedef enum {
    WIFI_STATE_IDLE        = 0,
    WIFI_STATE_CONNECTING  = 1,
    WIFI_STATE_CONNECTED   = 2,
    WIFI_STATE_DISCONNECTED = 3,
    WIFI_STATE_FAILED      = 4,
} WifiState;

// ── Status struct ──────────────────────────────────────────────────────────
// Read-only snapshot for other modules.
// Equivalent to Rust's WifiStatus struct and TinyGo's WifiStatus struct.
typedef struct {
    WifiState   state;
    char        ip[WIFI_IP_BUF_LEN];
    int32_t     rssi_dbm;       // signal strength, negative dBm
    uint32_t    connect_time_ms; // when we last connected
    uint32_t    reconnect_count; // how many reconnections so far
} WifiStatus;

// ── Global IP string ───────────────────────────────────────────────────────
// Defined here so display.c and http.c can extern it.
// In Rust: static WIFI_IP: Mutex<CriticalSectionRawMutex, String<16>>
// In TinyGo: package-level var protected by sync.Mutex
extern char g_ip_address[WIFI_IP_BUF_LEN];

// ── Public API ─────────────────────────────────────────────────────────────

// Initialize CYW43 hardware. Must be called before any other wifi_ function.
// Returns false if CYW43 initialization fails (hardware fault).
bool        wifi_init(void);

// Attempt to connect. Blocks until connected or max retries exhausted.
// Returns true if connected, false if all retries failed.
// On success, g_ip_address is populated and display is notified.
bool        wifi_connect(void);

// Poll function — call from main loop.
// Checks link status and triggers reconnection if disconnected.
// Never blocks.
void        wifi_poll(void);

// Returns true if currently connected with a valid IP.
bool        wifi_is_connected(void);

// Write current IP into buf (max len bytes). Writes "0.0.0.0" if not connected.
void        wifi_get_ip(char *buf, size_t len);

// Returns current RSSI in dBm. Returns 0 if not connected.
int32_t     wifi_get_rssi(void);

// Returns a snapshot of current wifi status.
WifiStatus  wifi_get_status(void);

// Returns human-readable state string.
const char *wifi_state_str(WifiState state);

// Set the onboard LED (lives on CYW43, not GPIO).
// Other modules must use this — they cannot use gpio_put() for the LED.
void        wifi_set_led(bool on);

#endif // WIFI_H

// wifi.c
//
// WiFi management for the basement monitor — Pico W / CYW43439.
//
// The Pico W's WiFi chip (CYW43439) is connected via SPI internally.
// The Pico SDK's cyw43_arch library abstracts this. We use the
// lwip_threadsafe_background variant — lwIP runs in interrupt context
// so we never need to call cyw43_arch_poll() manually.
//
// Architecture comparison:
//
//   C:      cyw43_arch_wifi_connect_timeout_ms() blocks the CPU.
//           lwIP IRQ still fires during the block but the main loop
//           is completely paused. Reconnection is polled from main loop
//           via wifi_poll() on a timestamp cadence.
//
//   Rust:   embassy-net + cyw43 crate. Connection is fully async —
//           wifi.join().await yields Embassy executor. Reconnection
//           runs in the same async task, yielding between retries.
//           Other tasks (sensors, display, HTTP) run normally during
//           the entire WiFi lifecycle.
//
//   TinyGo: cyw43 driver wraps the same CYW43 SPI protocol.
//           Connection blocks the calling goroutine but other goroutines
//           run if the driver has yield points internally.
//           Reconnection runs in a dedicated goroutine.

#include "wifi.h"
#include "display.h"
#include "pico/stdlib.h"
#include "pico/cyw43_arch.h"
#include "lwip/netif.h"
#include "lwip/ip4_addr.h"
#include "lwip/dns.h"
#include <stdio.h>
#include <string.h>

// ── Global state ───────────────────────────────────────────────────────────
// In Rust: static WIFI_STATUS: Mutex<CriticalSectionRawMutex, WifiStatus>
// In TinyGo: package-level var guarded by sync.Mutex
// In C: globals + critical_section — nothing prevents unsynchronized reads
char g_ip_address[WIFI_IP_BUF_LEN] = "0.0.0.0";

static WifiStatus  g_status = {
    .state          = WIFI_STATE_IDLE,
    .ip             = "0.0.0.0",
    .rssi_dbm       = 0,
    .connect_time_ms = 0,
    .reconnect_count = 0,
};

static bool     g_initialized      = false;
static uint32_t g_next_reconnect_ms = 0;
static uint32_t g_retry_backoff_ms  = WIFI_RETRY_BASE_MS;
static uint32_t g_led_blink_ms      = 0;
static bool     g_led_state         = false;

// ── LED helpers ────────────────────────────────────────────────────────────
// The Pico W onboard LED is connected to the CYW43 chip, not to a GPIO pin.
// You CANNOT use gpio_put(25, 1) on the Pico W — it does nothing or worse.
// You MUST use cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, value).
// This is a common Pico W gotcha. Centralizing it here prevents other
// modules from accidentally using the wrong API.

void wifi_set_led(bool on) {
    cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, on ? 1 : 0);
}

// Blink the LED — called from wifi_poll() during connecting state.
// Non-blocking: checks timestamp, toggles if due.
static void led_blink_poll(uint32_t now, uint32_t interval_ms) {
    if (now < g_led_blink_ms) return;
    g_led_blink_ms = now + interval_ms;
    g_led_state    = !g_led_state;
    wifi_set_led(g_led_state);
}

// ── IP address helpers ─────────────────────────────────────────────────────

static void update_ip(void) {
    struct netif *netif = netif_default;
    if (netif == NULL) {
        strncpy(g_status.ip, "0.0.0.0", WIFI_IP_BUF_LEN);
        strncpy(g_ip_address, "0.0.0.0", WIFI_IP_BUF_LEN);
        return;
    }
    const char *ip = ip4addr_ntoa(netif_ip4_addr(netif));
    strncpy(g_status.ip, ip, WIFI_IP_BUF_LEN - 1);
    g_status.ip[WIFI_IP_BUF_LEN - 1] = '\0';
    strncpy(g_ip_address, g_status.ip, WIFI_IP_BUF_LEN);

    // Notify display module so the status page shows the real IP.
    // In Rust: display task reads from STATE which wifi task updates.
    // In TinyGo: display.SetWifiIP(ip) updates the closure.
    // In C: display reads g_ip_address directly via extern.
    // The extern approach is the least explicit — any module can read
    // g_ip_address without going through wifi_get_ip().
    printf("[WIFI ] IP: %s\n", g_ip_address);
}

// ── RSSI reading ───────────────────────────────────────────────────────────

static int32_t read_rssi(void) {
    int32_t rssi = 0;
    // cyw43_wifi_get_rssi requires the CYW43 to be in station mode
    // and connected. Returns 0 on failure.
    if (g_status.state == WIFI_STATE_CONNECTED) {
        cyw43_wifi_get_rssi(&cyw43_state, &rssi);
    }
    return rssi;
}

// ── Single connection attempt ──────────────────────────────────────────────

static bool attempt_connect(void) {
    g_status.state = WIFI_STATE_CONNECTING;
    printf("[WIFI ] Connecting to '%s'...\n", WIFI_SSID);

    // This call blocks for up to WIFI_CONNECT_TIMEOUT_MS.
    // During this time:
    //   - lwIP IRQ fires normally (packets processed)
    //   - main loop is completely frozen
    //   - sensor polling stops
    //   - display stops updating
    //   - alarm stops pulsing
    //
    // In Rust: wifi.join(ssid, pass).await → other tasks run normally
    // In TinyGo: blocks calling goroutine, others may run (driver-dependent)
    // In C: everything stops — this is the fundamental C limitation here
    int result = cyw43_arch_wifi_connect_timeout_ms(
        WIFI_SSID,
        WIFI_PASSWORD,
        CYW43_AUTH_WPA2_AES_PSK,
        WIFI_CONNECT_TIMEOUT_MS
    );

    if (result != 0) {
        printf("[WIFI ] Connection failed: error %d\n", result);
        g_status.state = WIFI_STATE_DISCONNECTED;
        return false;
    }

    // Connected — read IP and signal strength
    update_ip();
    g_status.rssi_dbm       = read_rssi();
    g_status.state          = WIFI_STATE_CONNECTED;
    g_status.connect_time_ms = to_ms_since_boot(get_absolute_time());

    printf("[WIFI ] Connected — IP=%s RSSI=%ddBm reconnects=%lu\n",
           g_status.ip,
           g_status.rssi_dbm,
           g_status.reconnect_count);

    // Solid LED when connected
    wifi_set_led(true);

    return true;
}

// ── Public API ─────────────────────────────────────────────────────────────

bool wifi_init(void) {
    if (g_initialized) return true;

    printf("[WIFI ] Initializing CYW43...\n");

    // cyw43_arch_init_with_country sets the regulatory domain.
    // CYW43_COUNTRY_USA — change to your country code.
    // Using the wrong country code can violate radio regulations.
    if (cyw43_arch_init_with_country(CYW43_COUNTRY_USA) != 0) {
        printf("[WIFI ] CYW43 init failed — hardware fault?\n");
        return false;
    }

    // Station mode — we are a client, not an access point
    cyw43_arch_enable_sta_mode();

    // Set hostname for DHCP — shows up in router client list
    // netif_set_hostname(netif_default, WIFI_HOSTNAME);

    g_initialized = true;
    printf("[WIFI ] CYW43 initialized\n");

    // Start LED blinking to show we are alive but not connected
    wifi_set_led(false);

    return true;
}

bool wifi_connect(void) {
    if (!g_initialized) {
        printf("[WIFI ] wifi_connect() called before wifi_init()\n");
        return false;
    }

    uint32_t backoff = WIFI_RETRY_BASE_MS;

    for (int attempt = 1; attempt <= WIFI_MAX_RETRIES; attempt++) {
        printf("[WIFI ] Attempt %d/%d\n", attempt, WIFI_MAX_RETRIES);

        if (attempt_connect()) {
            g_retry_backoff_ms = WIFI_RETRY_BASE_MS; // reset backoff on success
            return true;
        }

        if (attempt < WIFI_MAX_RETRIES) {
            printf("[WIFI ] Retrying in %lums...\n", backoff);

            // Wait between retries — blink LED during wait.
            // Non-blocking wait: poll LED blink while waiting.
            // This is the C pattern for "do something while waiting"
            // without yielding — contrast with Rust's:
            //   Timer::after(backoff).await  (other tasks run freely)
            // and TinyGo's:
            //   time.Sleep(backoff)           (other goroutines run freely)
            uint32_t wait_start = to_ms_since_boot(get_absolute_time());
            while (to_ms_since_boot(get_absolute_time()) - wait_start < backoff) {
                uint32_t now = to_ms_since_boot(get_absolute_time());
                led_blink_poll(now, 250); // fast blink during retry wait
                sleep_ms(10);            // brief yield for lwIP IRQ
            }

            // Exponential backoff — double each retry, cap at max
            backoff *= 2;
            if (backoff > WIFI_RETRY_MAX_MS) {
                backoff = WIFI_RETRY_MAX_MS;
            }
        }
    }

    g_status.state = WIFI_STATE_FAILED;
    printf("[WIFI ] All %d attempts failed — running offline\n",
           WIFI_MAX_RETRIES);
    wifi_set_led(false); // LED off = offline
    return false;
}

void wifi_poll(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    switch (g_status.state) {
        case WIFI_STATE_CONNECTING:
            // Blink LED at 2Hz while connecting
            led_blink_poll(now, 500);
            break;

        case WIFI_STATE_CONNECTED:
            // Periodically check link status
            if (now < g_next_reconnect_ms) break;
            g_next_reconnect_ms = now + WIFI_RECONNECT_CHECK_MS;

            // Check if still connected
            int link = cyw43_wifi_link_status(
                &cyw43_state, CYW43_ITF_STA
            );
            if (link != CYW43_LINK_JOIN) {
                printf("[WIFI ] Link lost (status=%d) — reconnecting\n",
                       link);
                g_status.state = WIFI_STATE_DISCONNECTED;
                wifi_set_led(false);

                // Update IP to show disconnected
                strncpy(g_ip_address, "0.0.0.0", WIFI_IP_BUF_LEN);
                strncpy(g_status.ip,  "0.0.0.0", WIFI_IP_BUF_LEN);

                // Reconnect — this blocks the main loop again.
                // In Rust/TinyGo, reconnection runs asynchronously.
                // In C we accept the brief freeze — sensors and display
                // will miss a few cycles during reconnection.
                g_status.reconnect_count++;
                printf("[WIFI ] Reconnect attempt #%lu\n",
                       g_status.reconnect_count);
                wifi_connect();
            } else {
                // Still connected — update RSSI
                g_status.rssi_dbm = read_rssi();
            }
            break;

        case WIFI_STATE_DISCONNECTED:
            // Reconnect with backoff
            if (now < g_next_reconnect_ms) {
                led_blink_poll(now, 500);
                break;
            }
            g_status.reconnect_count++;
            if (!wifi_connect()) {
                // Failed — back off before next attempt
                g_retry_backoff_ms = (g_retry_backoff_ms * 2 < WIFI_RETRY_MAX_MS)
                                   ? g_retry_backoff_ms * 2
                                   : WIFI_RETRY_MAX_MS;
                g_next_reconnect_ms = now + g_retry_backoff_ms;
            }
            break;

        case WIFI_STATE_FAILED:
        case WIFI_STATE_IDLE:
        default:
            // Slow LED blink — alive but offline
            led_blink_poll(now, 2000);
            break;
    }
}

bool wifi_is_connected(void) {
    return g_status.state == WIFI_STATE_CONNECTED;
}

void wifi_get_ip(char *buf, size_t len) {
    strncpy(buf, g_ip_address, len - 1);
    buf[len - 1] = '\0';
}

int32_t wifi_get_rssi(void) {
    return g_status.rssi_dbm;
}

WifiStatus wifi_get_status(void) {
    // Return a copy — snapshot pattern same as Rust's
    // STATE.lock().await + clone() and TinyGo's stateMu.Lock() + copy
    return g_status;
}

const char *wifi_state_str(WifiState state) {
    switch (state) {
        case WIFI_STATE_IDLE:         return "IDLE";
        case WIFI_STATE_CONNECTING:   return "CONNECTING";
        case WIFI_STATE_CONNECTED:    return "CONNECTED";
        case WIFI_STATE_DISCONNECTED: return "DISCONNECTED";
        case WIFI_STATE_FAILED:       return "FAILED";
        default:                      return "UNKNOWN";
    }
}

Rust `wifi.rs` Implementation

// src/wifi.rs
//
// WiFi management for the basement monitor — Pico W / CYW43439.
//
// Uses embassy-net + cyw43 crate for fully async WiFi management.
// The key difference from C and TinyGo:
//   Connection, DHCP, and reconnection all use .await — the Embassy
//   executor runs sensor, display, alarm, and HTTP tasks normally
//   during the entire WiFi lifecycle. Nothing stalls.
//
// The Pico W LED lives on the CYW43 chip, not on GPIO.
// cyw43::Control::gpio_set() is the only correct way to drive it.
// This is the same constraint as C's cyw43_arch_gpio_put().

use core::str::from_utf8;

use cyw43::JoinOptions;
use cyw43_pio::PioSpi;
use defmt::*;
use embassy_executor::Spawner;
use embassy_net::{
    Config, Stack, StackResources,
    dns::DnsSocket,
    tcp::TcpSocket,
};
use embassy_rp::{
    gpio::{Level, Output},
    peripherals::{DMA_CH0, PIN_23, PIN_24, PIN_25, PIN_29, PIO0},
    pio::Pio,
};
use embassy_sync::{
    blocking_mutex::raw::CriticalSectionRawMutex,
    mutex::Mutex,
};
use embassy_time::{Duration, Timer};
use heapless::String;
use static_cell::StaticCell;

// ── Credentials ────────────────────────────────────────────────────────────
// Set via environment variables at build time in build.rs:
//   println!("cargo:rustc-env=WIFI_SSID={}", ssid);
// Never hardcode credentials in source.
const WIFI_SSID:     &str = env!("WIFI_SSID");
const WIFI_PASSWORD: &str = env!("WIFI_PASSWORD");

// ── Configuration ──────────────────────────────────────────────────────────
const MAX_RETRIES:       u32      = 5;
const RETRY_BASE:        Duration = Duration::from_secs(2);
const RETRY_MAX:         Duration = Duration::from_secs(30);
const RECONNECT_CHECK:   Duration = Duration::from_secs(5);
const CONNECT_TIMEOUT:   Duration = Duration::from_secs(30);

// ── Shared WiFi status ─────────────────────────────────────────────────────
// Exposed to other tasks via Mutex — same pattern as SensorState in main.rs.
// C equivalent: g_ip_address global + g_status struct.
// TinyGo equivalent: package-level vars protected by sync.Mutex.

#[derive(Clone, defmt::Format)]
pub enum WifiState {
    Idle,
    Connecting,
    Connected,
    Disconnected,
    Failed,
}

#[derive(Clone)]
pub struct WifiStatus {
    pub state:           WifiState,
    pub ip:              String<16>,
    pub rssi_dbm:        i32,
    pub reconnect_count: u32,
}

impl WifiStatus {
    const fn new() -> Self {
        Self {
            state:           WifiState::Idle,
            ip:              String::new(),
            rssi_dbm:        0,
            reconnect_count: 0,
        }
    }
}

pub static WIFI_STATUS: Mutex<CriticalSectionRawMutex, WifiStatus> =
    Mutex::new(WifiStatus::new());

// ── Static resources ───────────────────────────────────────────────────────
// embassy-net requires static storage for the network stack.
// StaticCell ensures these are initialized exactly once.
// C equivalent: global structs allocated at link time.

static STATE:     StaticCell<cyw43::State>    = StaticCell::new();
static RESOURCES: StaticCell<StackResources<4>> = StaticCell::new();

// ── CYW43 firmware ────────────────────────────────────────────────────────
// The CYW43 chip requires firmware loaded at runtime over SPI.
// These blobs are included at compile time from the pico-sdk firmware files.
// C equivalent: cyw43_arch_init() loads these internally.
include!(concat!(env!("OUT_DIR"), "/cyw43_fw.rs"));

// ── WiFi init — called from main.rs ───────────────────────────────────────
// Returns the network Stack reference used by the HTTP server task.
// Spawns two internal tasks: cyw43_task (chip driver) and net_task (lwIP).

pub async fn init(
    spawner:  Spawner,
    pwr:      PIN_23,
    cs:       PIN_24,
    dio:      PIN_25,  // Pico W LED is also on this line via CYW43
    clk:      PIN_29,
    pio:      PIO0,
    dma:      DMA_CH0,
    irqs:     crate::Irqs,
) -> &'static Stack<cyw43::NetDriver<'static>> {

    // ── SPI to CYW43 ──────────────────────────────────────────────────
    // The CYW43439 is connected internally via PIO-based SPI.
    // PIO (Programmable I/O) runs the SPI protocol in hardware —
    // freeing the CPU entirely during transfers.
    // C equivalent: handled inside cyw43_arch_init() transparently.
    let pwr = Output::new(pwr, Level::Low);
    let cs  = Output::new(cs,  Level::High);
    let mut pio = Pio::new(pio, irqs);

    let spi = PioSpi::new(
        &mut pio.common,
        pio.sm0,
        pio.irq0,
        cs,
        dio,
        clk,
        dma,
    );

    // ── CYW43 driver init ──────────────────────────────────────────────
    let state = STATE.init(cyw43::State::new());
    let (net_device, mut control, runner) = cyw43::new(
        state,
        pwr,
        spi,
        CYW43_FW,      // firmware blob included at compile time
    ).await;

    // Spawn the CYW43 background task — handles chip communication
    // Equivalent to cyw43_arch's background interrupt handler in C
    spawner.spawn(cyw43_task(runner)).unwrap();

    // ── Network stack (embassy-net / lwIP equivalent) ──────────────────
    // DHCP configuration — same as C's lwIP DHCP
    let config = Config::dhcpv4(Default::default());

    // Random seed for TCP sequence numbers — use RP2040 ROSC
    let seed = embassy_rp::clocks::rosc_random_u64();

    let resources = RESOURCES.init(StackResources::<4>::new());
    let (stack, runner) = embassy_net::new(
        net_device,
        config,
        resources,
        seed,
    );

    // Spawn the network stack task
    spawner.spawn(net_task(runner)).unwrap();

    // ── Spawn the WiFi management task ────────────────────────────────
    // This is the async equivalent of wifi_connect() + wifi_poll()
    // in C — but non-blocking. The sensor, display, and alarm tasks
    // run normally while this task is waiting for DHCP or reconnecting.
    spawner.spawn(wifi_task(control, stack)).unwrap();

    stack
}

// ── CYW43 background task ──────────────────────────────────────────────────
// Runs the chip driver — must never be starved of CPU time.
// Embassy's cooperative scheduler ensures it runs between other task yields.
// C equivalent: interrupt handler registered by cyw43_arch_init().

#[embassy_executor::task]
async fn cyw43_task(
    runner: cyw43::Runner<
        'static,
        Output<'static>,
        PioSpi<'static, PIO0, 0, DMA_CH0>,
    >,
) -> ! {
    runner.run().await
}

// ── Network stack task ─────────────────────────────────────────────────────
// Runs the embassy-net TCP/IP stack — equivalent to lwIP's background
// processing in C's threadsafe_background mode.

#[embassy_executor::task]
async fn net_task(
    mut runner: embassy_net::Runner<'static, cyw43::NetDriver<'static>>,
) -> ! {
    runner.run().await
}

// ── WiFi management task ───────────────────────────────────────────────────
// Handles connection, DHCP, LED, RSSI polling, and reconnection.
// All async — other tasks run during every .await point.
// This is the cleanest of the three implementations for this reason.

#[embassy_executor::task]
async fn wifi_task(
    mut control: cyw43::Control<'static>,
    stack:       &'static Stack<cyw43::NetDriver<'static>>,
) {
    // Set hostname for DHCP
    // stack.set_hostname("basement-monitor");

    info!("WiFi task started");

    let mut reconnect_count: u32 = 0;

    // ── Initial connection with retry + backoff ────────────────────────
    loop {
        match connect_with_retry(&mut control).await {
            Ok(()) => break,
            Err(()) => {
                error!("All WiFi connection attempts failed — offline mode");
                update_status(|s| s.state = WifiState::Failed).await;
                // Wait before trying again — deep sleep
                Timer::after(Duration::from_secs(60)).await;
                // Loop back to retry
            }
        }
    }

    // ── Wait for DHCP lease ────────────────────────────────────────────
    // embassy-net handles DHCP internally — we wait until config is ready.
    // C equivalent: IP is available immediately after
    //   cyw43_arch_wifi_connect_timeout_ms() returns.
    info!("Waiting for DHCP...");
    update_status(|s| s.state = WifiState::Connecting).await;

    loop {
        if let Some(config) = stack.config_v4() {
            let mut ip_str: String<16> = String::new();
            let ip = config.address.address();
            // Format IP into heapless String — zero allocation
            core::fmt::write(
                &mut ip_str,
                format_args!("{}.{}.{}.{}",
                    ip.0[0], ip.0[1], ip.0[2], ip.0[3]),
            ).ok();

            info!("DHCP lease obtained — IP: {}", ip_str.as_str());

            update_status(|s| {
                s.state = WifiState::Connected;
                s.ip    = ip_str.clone();
            }).await;

            // Solid LED — connected
            control.gpio_set(0, true).await;
            break;
        }
        Timer::after(Duration::from_millis(500)).await;
    }

    // ── Steady-state: monitor connection, poll RSSI ────────────────────
    loop {
        Timer::after(RECONNECT_CHECK).await;

        // Check link status
        if !stack.is_link_up() {
            warn!("WiFi link lost — reconnecting");

            // LED off — disconnected
            control.gpio_set(0, false).await;

            reconnect_count += 1;
            update_status(|s| {
                s.state           = WifiState::Disconnected;
                s.reconnect_count = reconnect_count;
                s.ip              = String::new();
            }).await;

            // Reconnect — other tasks run normally during this entire process
            // This is the most significant advantage over C:
            // the sensor task is still polling, the alarm is still pulsing,
            // the display is still refreshing — all while we reconnect.
            match connect_with_retry(&mut control).await {
                Ok(()) => {
                    // Wait for new DHCP lease
                    loop {
                        if let Some(config) = stack.config_v4() {
                            let mut ip_str: String<16> = String::new();
                            let ip = config.address.address();
                            core::fmt::write(
                                &mut ip_str,
                                format_args!("{}.{}.{}.{}",
                                    ip.0[0], ip.0[1], ip.0[2], ip.0[3]),
                            ).ok();
                            info!("Reconnected — IP: {} (reconnect #{})",
                                ip_str.as_str(), reconnect_count);
                            update_status(|s| {
                                s.state = WifiState::Connected;
                                s.ip    = ip_str.clone();
                            }).await;
                            control.gpio_set(0, true).await;
                            break;
                        }
                        Timer::after(Duration::from_millis(500)).await;
                    }
                }
                Err(()) => {
                    error!("Reconnection failed — continuing offline");
                    update_status(|s| s.state = WifiState::Failed).await;
                }
            }
        } else {
            // Still connected — update RSSI
            // cyw43 RSSI read is async — yields to other tasks
            if let Ok(rssi) = control.rssi().await {
                update_status(|s| s.rssi_dbm = rssi as i32).await;
            }
        }
    }
}

// ── Connection with retry + exponential backoff ────────────────────────────

async fn connect_with_retry(
    control: &mut cyw43::Control<'static>,
) -> Result<(), ()> {
    let mut backoff = RETRY_BASE;

    for attempt in 1..=MAX_RETRIES {
        info!("WiFi connect attempt {}/{}", attempt, MAX_RETRIES);

        // Blink LED during connection attempt
        control.gpio_set(0, true).await;

        // join() is fully async — other tasks run during the handshake.
        // C equivalent: cyw43_arch_wifi_connect_timeout_ms() — blocks CPU.
        // TinyGo equivalent: dev.ConnectWPA2() — blocks goroutine.
        let result = embassy_time::with_timeout(
            CONNECT_TIMEOUT,
            control.join(WIFI_SSID, JoinOptions::new(WIFI_PASSWORD.as_bytes())),
        ).await;

        control.gpio_set(0, false).await;

        match result {
            Ok(Ok(())) => {
                info!("WiFi connected to '{}'", WIFI_SSID);
                return Ok(());
            }
            Ok(Err(e)) => {
                warn!("Connect failed (attempt {}): status={}", attempt, e.status);
            }
            Err(_) => {
                warn!("Connect timed out (attempt {})", attempt);
            }
        }

        if attempt < MAX_RETRIES {
            info!("Retrying in {}ms...", backoff.as_millis());

            // Blink LED during backoff wait — other tasks run freely
            let blink_end = embassy_time::Instant::now() + backoff;
            while embassy_time::Instant::now() < blink_end {
                control.gpio_set(0, true).await;
                Timer::after(Duration::from_millis(250)).await;
                control.gpio_set(0, false).await;
                Timer::after(Duration::from_millis(250)).await;
            }

            // Exponential backoff
            backoff = (backoff * 2).min(RETRY_MAX);
        }
    }

    Err(())
}

// ── Status update helper ───────────────────────────────────────────────────
// Locks WIFI_STATUS, applies mutation, unlocks.
// Same pattern as UpdateState() in main.rs.

async fn update_status(f: impl FnOnce(&mut WifiStatus)) {
    let mut status = WIFI_STATUS.lock().await;
    f(&mut *status);
}

// ── Public getters ─────────────────────────────────────────────────────────
// Called by http.rs and display.rs to read current WiFi state.

pub async fn get_ip() -> String<16> {
    WIFI_STATUS.lock().await.ip.clone()
}

pub async fn get_status() -> WifiStatus {
    WIFI_STATUS.lock().await.clone()
}

pub fn is_connected() -> bool {
    // Non-async check using try_lock — returns false if lock is held.
    // Safe for status bar display — occasional miss is acceptable.
    WIFI_STATUS.try_lock()
        .map(|s| matches!(s.state, WifiState::Connected))
        .unwrap_or(false)
}

Now, your basement water monitor has internet connectivity!

Implementing the Built In Web Server

Routes:
  GET  /              → HTML dashboard (auto-refresh 3s)
  GET  /sensors       → JSON sensor snapshot
  GET  /wifi          → JSON wifi status (ip, rssi, state, reconnects)
  GET  /alarm         → JSON alarm status (level, latched, relay)
  POST /alarm/ack     → acknowledge latched alarm, returns JSON
  GET  /health        → "OK" plaintext — for uptime monitors
  GET  /metrics       → plaintext key=value for Prometheus scraping
  *                   → 404

Hardening:
  Request timeout     → close connection if no data in 10s
  Max body size       → reject requests > 512 bytes
  Concurrent limit    → max 3 simultaneous connections (memory budget)
  Connection: close   → no persistent connections on embedded
  CORS header         → Access-Control-Allow-Origin: *
  Content-Length      → always set — no chunked encoding

Shared state reads:
  SensorState snapshot
  WifiStatus snapshot
  AlarmState snapshot

Go `http/server.go` Implementation

// http/server.go
//
// HTTP/1.0 server for the basement monitor.
// Built on TinyGo's net package (lwIP underneath).
//
// Routes:
//   GET  /          → HTML dashboard
//   GET  /sensors   → JSON sensor snapshot
//   GET  /wifi      → JSON WiFi status
//   GET  /alarm     → JSON alarm status
//   POST /alarm/ack → acknowledge latched alarm
//   GET  /health    → plaintext OK
//   GET  /metrics   → Prometheus plaintext
//   *               → 404
//
// TinyGo net.Listen wraps lwIP's raw TCP API behind Go's standard
// net.Listener interface — same TCP stack as C, cleaner surface.
// Goroutine-per-connection is idiomatic Go. On a Pico W with 264KB RAM
// we cap at maxConnections goroutines — the embedded equivalent of
// your room.WaitingRoom capacity limit.
//
// Allocation note:
//   fmt.Sprintf allocates on every route handler call.
//   At human-request frequency this is acceptable.
//   A production TinyGo server would use a pre-allocated byte buffer
//   and strconv to eliminate allocations — at the cost of readability.

package http

import (
    "basement-monitor/alarm"
    "basement-monitor/sensors"
    "basement-monitor/wifi"
    "fmt"
    "net"
    "strings"
    "sync/atomic"
    "time"
)

// ── Configuration ──────────────────────────────────────────────────────────
const (
    httpPort       = ":80"
    maxConnections = 3
    requestTimeout = 10 * time.Second
    requestBufSize = 512
)

// ── Active connection counter ──────────────────────────────────────────────
// Atomic counter — safe to read/write from multiple goroutines.
// C equivalent: g_active_connections uint8.
// Rust equivalent: #[embassy_executor::task(pool_size=3)] — static bound.
var activeConns int32

// ── ServeTask ──────────────────────────────────────────────────────────────

// ServeTask starts the HTTP listener and accepts connections.
// Runs as a goroutine spawned from main.go after WiFi connects.
// Equivalent to http_server_init() in C and server_task() in Rust.

func ServeTask(
    getState   func() sensors.SensorState,
    getAlarm   func() alarm.AlarmState,
    acknowledge func(),
) {
    ln, err := net.Listen("tcp", httpPort)
    if err != nil {
        println("[HTTP ] Failed to listen:", err.Error())
        return
    }
    println("[HTTP ] Listening on port 80")

    for {
        conn, err := ln.Accept()
        if err != nil {
            println("[HTTP ] Accept error:", err.Error())
            time.Sleep(100 * time.Millisecond)
            continue
        }

        // Enforce concurrent connection limit.
        // Same cap as C's HTTP_MAX_CONNECTIONS and Rust's pool_size=3.
        // This is your room.WaitingRoom.Init(3) equivalent —
        // excess connections are rejected immediately rather than queued.
        // A full room implementation would queue them with position tracking.
        current := atomic.AddInt32(&activeConns, 1)
        if current > maxConnections {
            atomic.AddInt32(&activeConns, -1)
            println("[HTTP ] Connection limit reached — rejecting")
            conn.Write([]byte(
                "HTTP/1.0 503 Service Unavailable\r\n" +
                "Content-Length: 19\r\n\r\n" +
                "Too many connections"))
            conn.Close()
            continue
        }

        println("[HTTP ] Client connected (", current, "/", maxConnections, "active)")

        // Goroutine per connection — each runs independently.
        // Equivalent to Rust's connection_task() async task.
        // C has no equivalent — it handles one connection at a time
        // via the lwIP callback state machine.
        go func(c net.Conn) {
            defer func() {
                atomic.AddInt32(&activeConns, -1)
                c.Close()
            }()
            handleConn(c, getState, getAlarm, acknowledge)
        }(conn)
    }
}

// ── Connection handler ─────────────────────────────────────────────────────

func handleConn(
    conn        net.Conn,
    getState    func() sensors.SensorState,
    getAlarm    func() alarm.AlarmState,
    acknowledge func(),
) {
    // Set read deadline — close if client takes too long.
    // C equivalent: conn->open_time_ms checked in http_server_poll().
    // Rust equivalent: with_timeout(REQUEST_TIMEOUT, ...).await.
    conn.SetDeadline(time.Now().Add(requestTimeout))

    buf := make([]byte, requestBufSize)
    n, err := conn.Read(buf)
    if err != nil || n == 0 {
        return
    }

    request := string(buf[:n])

    // Route
    switch {
    case strings.Contains(request, " /sensors"):
        serveSensors(conn, getState)
    case strings.Contains(request, " /wifi"):
        serveWifi(conn)
    case strings.Contains(request, " /alarm/ack"):
        serveAlarmAck(conn, request, acknowledge, getAlarm)
    case strings.Contains(request, " /alarm"):
        serveAlarm(conn, getAlarm)
    case strings.Contains(request, " /metrics"):
        serveMetrics(conn, getState, getAlarm)
    case strings.Contains(request, " /health"):
        serveHealth(conn)
    case strings.Contains(request, " /"):
        serveDashboard(conn, getState, getAlarm)
    default:
        serve404(conn)
    }
}

// ── Response helper ────────────────────────────────────────────────────────

func sendResponse(
    conn        net.Conn,
    status      int,
    statusText  string,
    contentType string,
    body        string,
) {
    // fmt.Sprintf allocates — GC cost.
    // At HTTP request frequency (human scale) this is acceptable.
    // Rust uses heapless::String — zero allocation.
    // C uses snprintf into static char[] — zero allocation.
    headers := fmt.Sprintf(
        "HTTP/1.0 %d %s\r\n"+
        "Content-Type: %s\r\n"+
        "Content-Length: %d\r\n"+
        "Connection: close\r\n"+
        "Access-Control-Allow-Origin: *\r\n"+
        "Cache-Control: no-cache\r\n"+
        "\r\n",
        status, statusText,
        contentType,
        len(body),
    )
    conn.Write([]byte(headers))
    conn.Write([]byte(body))
}

func sendJSON(conn net.Conn, body string) {
    sendResponse(conn, 200, "OK", "application/json", body)
}

func sendHTML(conn net.Conn, body string) {
    sendResponse(conn, 200, "OK", "text/html; charset=utf-8", body)
}

func sendText(conn net.Conn, body string) {
    sendResponse(conn, 200, "OK", "text/plain", body)
}

func serve404(conn net.Conn) {
    sendResponse(conn, 404, "Not Found", "text/plain", "Not Found")
}

// ── Route handlers ─────────────────────────────────────────────────────────

func serveSensors(conn net.Conn, getState func() sensors.SensorState) {
    s := getState()
    body := fmt.Sprintf(
        `{"water":%t,"temp_c":%.1f,"humidity_pct":%.1f,`+
        `"motion":%t,"co_ppm":%d,"alarm_active":%t}`,
        s.WaterDetected,
        s.TemperatureC,
        s.HumidityPct,
        s.MotionDetected,
        s.CoPpm,
        s.AlarmActive,
    )
    sendJSON(conn, body)
}

func serveWifi(conn net.Conn) {
    ws := wifi.GetStatus()
    body := fmt.Sprintf(
        `{"state":"%s","ip":"%s","rssi_dbm":%d,"reconnect_count":%d}`,
        ws.State.String(),
        ws.IP,
        ws.RSSIdbm,
        ws.ReconnectCount,
    )
    sendJSON(conn, body)
}

func serveAlarm(conn net.Conn, getAlarm func() alarm.AlarmState) {
    a := getAlarm()
    latched := a.WaterLatched || a.CoCritLatched
    body := fmt.Sprintf(
        `{"level":"%s","active":%t,"latched":%t,`+
        `"water_latched":%t,"co_critical_latched":%t,"relay_active":%t}`,
        a.Level.String(),
        a.Active,
        latched,
        a.WaterLatched,
        a.CoCritLatched,
        a.RelayActive,
    )
    sendJSON(conn, body)
}

func serveAlarmAck(
    conn        net.Conn,
    request     string,
    acknowledge func(),
    getAlarm    func() alarm.AlarmState,
) {
    if !strings.HasPrefix(request, "POST") {
        sendResponse(conn, 405, "Method Not Allowed",
            "text/plain", "Method Not Allowed")
        return
    }

    acknowledge()

    // Brief wait for alarm goroutine to process the acknowledge
    time.Sleep(50 * time.Millisecond)

    a := getAlarm()
    body := fmt.Sprintf(
        `{"acknowledged":true,"level":"%s"}`,
        a.Level.String(),
    )
    sendJSON(conn, body)
}

func serveHealth(conn net.Conn) {
    sendText(conn, "OK")
}

func serveMetrics(
    conn     net.Conn,
    getState func() sensors.SensorState,
    getAlarm func() alarm.AlarmState,
) {
    s := getState()
    ws := wifi.GetStatus()
    a := getAlarm()

    waterVal  := 0
    if s.WaterDetected  { waterVal  = 1 }
    motionVal := 0
    if s.MotionDetected { motionVal = 1 }

    body := fmt.Sprintf(
        "# TYPE basement_water_detected gauge\n"+
        "basement_water_detected %d\n"+
        "# TYPE basement_temperature_celsius gauge\n"+
        "basement_temperature_celsius %.2f\n"+
        "# TYPE basement_humidity_percent gauge\n"+
        "basement_humidity_percent %.2f\n"+
        "# TYPE basement_motion_detected gauge\n"+
        "basement_motion_detected %d\n"+
        "# TYPE basement_co_ppm gauge\n"+
        "basement_co_ppm %d\n"+
        "# TYPE basement_alarm_level gauge\n"+
        "basement_alarm_level %d\n"+
        "# TYPE basement_wifi_rssi_dbm gauge\n"+
        "basement_wifi_rssi_dbm %d\n"+
        "# TYPE basement_wifi_reconnects counter\n"+
        "basement_wifi_reconnects %d\n",
        waterVal,
        s.TemperatureC,
        s.HumidityPct,
        motionVal,
        s.CoPpm,
        int(a.Level),
        ws.RSSIdbm,
        ws.ReconnectCount,
    )

    sendResponse(conn, 200, "OK",
        "text/plain; version=0.0.4", body)
}

func serveDashboard(
    conn     net.Conn,
    getState func() sensors.SensorState,
    getAlarm func() alarm.AlarmState,
) {
    s  := getState()
    ws := wifi.GetStatus()
    a  := getAlarm()

    waterClass := ""
    if s.WaterDetected { waterClass = "alert" }
    waterColor := "ok"
    if s.WaterDetected { waterColor = "danger" }
    waterText := "Dry"
    if s.WaterDetected { waterText = "WATER DETECTED" }
    alarmColor := "ok"
    if s.AlarmActive { alarmColor = "danger" }
    coColor := "ok"
    if s.CoPpm >= 50 { coColor = "warn" }
    motionText := "Clear"
    if s.MotionDetected { motionText = "Detected" }

    body := fmt.Sprintf(`<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="3">
  <title>Basement Monitor</title>
  <style>
    body{font-family:system-ui;background:#0f1117;color:#e2e8f0;
         max-width:600px;margin:2rem auto;padding:1rem}
    h1{color:#6c8ef5}
    .card{background:#1a1d27;border-radius:8px;padding:1rem;margin:.5rem 0}
    .alert{background:#7f1d1d;border:1px solid #ef4444}
    .ok{color:#34d399}.warn{color:#fbbf24}
    .danger{color:#ef4444;font-weight:bold}
    a{color:#6c8ef5}
  </style>
</head>
<body>
  <h1>Basement Monitor</h1>
  <div class="card %s">
    <b>Water:</b> <span class="%s">%s</span>
  </div>
  <div class="card">
    <b>Temp:</b> %.1f&deg;C &nbsp; <b>Humidity:</b> %.1f%%
  </div>
  <div class="card">
    <b>Motion:</b> %s &nbsp;
    <b>CO:</b> <span class="%s">%d ppm</span>
  </div>
  <div class="card">
    <b>Alarm:</b> <span class="%s">%s</span>
    &nbsp;
    <a href="#" onclick="fetch('/alarm/ack',{method:'POST'});return false;">
      Acknowledge
    </a>
  </div>
  <div class="card">
    <b>WiFi:</b> %s &nbsp; <b>RSSI:</b> %ddBm &nbsp;
    <b>Reconnects:</b> %d
  </div>
  <p style="color:#475569;font-size:.8rem">
    Auto-refresh 3s &middot;
    <a href="/sensors">JSON</a> &middot;
    <a href="/metrics">Metrics</a> &middot;
    <a href="/health">Health</a>
  </p>
</body>
</html>`,
        waterClass, waterColor, waterText,
        s.TemperatureC, s.HumidityPct,
        motionText, coColor, s.CoPpm,
        alarmColor, a.Level.String(),
        ws.IP, ws.RSSIdbm, ws.ReconnectCount,
    )

    sendHTML(conn, body)
}

C `http.h` | `http.c` Implementation

// http.h
#ifndef HTTP_H
#define HTTP_H

#include <stdbool.h>
#include <stdint.h>
#include "lwip/tcp.h"

// ── Configuration ──────────────────────────────────────────────────────────
#define HTTP_PORT               80
#define HTTP_MAX_CONNECTIONS    3       // memory budget: 3 × conn struct
#define HTTP_REQUEST_MAX        512     // max request bytes to read
#define HTTP_BODY_MAX           2048    // max response body bytes
#define HTTP_RESPONSE_MAX       2560    // body + headers
#define HTTP_TIMEOUT_MS         10000   // close if idle for 10s

// ── Connection state ───────────────────────────────────────────────────────
// One per active TCP connection.
// Equivalent to Rust's per-accept TcpSocket and TinyGo's net.Conn.
typedef struct {
    struct tcp_pcb *pcb;
    uint8_t         req_buf[HTTP_REQUEST_MAX];
    uint16_t        req_len;
    uint32_t        open_time_ms;   // for timeout enforcement
    bool            responded;
    bool            closed;
} HttpConn;

// ── Public API ─────────────────────────────────────────────────────────────
void http_server_init(void);
void http_server_poll(void);    // call from main loop — checks timeouts

#endif // HTTP_H

// http.c
//
// HTTP/1.0 server for the basement monitor.
// Built on lwIP raw TCP API.
//
// Routes:
//   GET  /          → HTML dashboard
//   GET  /sensors   → JSON sensor snapshot
//   GET  /wifi      → JSON WiFi status
//   GET  /alarm     → JSON alarm status
//   POST /alarm/ack → acknowledge latched alarm
//   GET  /health    → plaintext OK
//   GET  /metrics   → Prometheus-style key=value
//   *               → 404
//
// Architecture:
//   lwIP raw API is callback-driven. The mental model is:
//     on_accept()  → new connection arrives
//     on_recv()    → request bytes arrive (may be called multiple times)
//     on_sent()    → response bytes acknowledged
//     on_error()   → fatal error, conn already freed by lwIP
//     conn_close() → we initiate close
//
//   This is the most complex of the three implementations because
//   lwIP raw API requires you to manage partial reads manually.
//   A single HTTP request may arrive across multiple on_recv() calls.
//   We buffer into req_buf until we see \r\n\r\n (end of headers)
//   then route and respond.
//
//   Rust/embassy-net: socket.read(&mut buf).await — linear, one call.
//   TinyGo/net:       conn.Read(buf) — linear, one call.
//   C/lwIP raw:       on_recv() callback, may be called N times.

#include "http.h"
#include "sensors.h"
#include "alarm.h"
#include "wifi.h"
#include "pico/stdlib.h"
#include "lwip/tcp.h"
#include "lwip/err.h"
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

// ── Connection pool ────────────────────────────────────────────────────────
// Fixed pool avoids malloc() — same philosophy as Rust's heapless.
// We pre-allocate HTTP_MAX_CONNECTIONS slots and reuse them.
// If all slots are full, new connections are rejected immediately.
// This is the embedded equivalent of your room.WaitingRoom cap.

static HttpConn  g_conn_pool[HTTP_MAX_CONNECTIONS];
static bool      g_conn_used[HTTP_MAX_CONNECTIONS];
static uint8_t   g_active_connections = 0;

static struct tcp_pcb *g_listen_pcb = NULL;

// ── Static response buffers ────────────────────────────────────────────────
// Static (not stack) because they are large and lwIP callbacks may
// be called from interrupt context on some configurations.
// Making them static ensures they don't blow the stack or get
// optimized away.
// NOT reentrant — only safe because we handle one request at a time
// per connection and lwIP's threadsafe_background mode serializes
// callback invocation.
static char g_body[HTTP_BODY_MAX];
static char g_response[HTTP_RESPONSE_MAX];

// ── Connection pool management ─────────────────────────────────────────────

static HttpConn *conn_alloc(void) {
    for (int i = 0; i < HTTP_MAX_CONNECTIONS; i++) {
        if (!g_conn_used[i]) {
            g_conn_used[i] = true;
            memset(&g_conn_pool[i], 0, sizeof(HttpConn));
            g_conn_pool[i].open_time_ms =
                to_ms_since_boot(get_absolute_time());
            g_active_connections++;
            return &g_conn_pool[i];
        }
    }
    return NULL; // pool exhausted
}

static void conn_free(HttpConn *conn) {
    for (int i = 0; i < HTTP_MAX_CONNECTIONS; i++) {
        if (&g_conn_pool[i] == conn) {
            g_conn_used[i] = false;
            if (g_active_connections > 0) g_active_connections--;
            return;
        }
    }
}

// ── Response helpers ───────────────────────────────────────────────────────

// Send a complete HTTP response and close the connection.
// All routes funnel through here — single point for headers.
static void send_response(
    struct tcp_pcb *pcb,
    HttpConn       *conn,
    uint16_t        status_code,
    const char     *status_text,
    const char     *content_type,
    const char     *body,
    size_t          body_len
) {
    int resp_len = snprintf(g_response, sizeof(g_response),
        "HTTP/1.0 %u %s\r\n"
        "Content-Type: %s\r\n"
        "Content-Length: %zu\r\n"
        "Connection: close\r\n"
        "Access-Control-Allow-Origin: *\r\n"
        "Cache-Control: no-cache\r\n"
        "\r\n",
        status_code, status_text,
        content_type,
        body_len
    );

    if (resp_len < 0 || resp_len >= (int)sizeof(g_response)) {
        printf("[HTTP ] Response header overflow\n");
        return;
    }

    // Write headers
    err_t err = tcp_write(pcb, g_response, (u16_t)resp_len,
                          TCP_WRITE_FLAG_COPY);
    if (err != ERR_OK) {
        printf("[HTTP ] tcp_write headers failed: %d\n", err);
        return;
    }

    // Write body
    if (body && body_len > 0) {
        err = tcp_write(pcb, body, (u16_t)body_len, TCP_WRITE_FLAG_COPY);
        if (err != ERR_OK) {
            printf("[HTTP ] tcp_write body failed: %d\n", err);
            return;
        }
    }

    tcp_output(pcb);
    conn->responded = true;
}

static void send_json(struct tcp_pcb *pcb, HttpConn *conn,
                      const char *json, size_t len) {
    send_response(pcb, conn, 200, "OK",
                  "application/json", json, len);
}

static void send_html(struct tcp_pcb *pcb, HttpConn *conn,
                      const char *html, size_t len) {
    send_response(pcb, conn, 200, "OK",
                  "text/html; charset=utf-8", html, len);
}

static void send_text(struct tcp_pcb *pcb, HttpConn *conn,
                      const char *text) {
    send_response(pcb, conn, 200, "OK",
                  "text/plain", text, strlen(text));
}

static void send_404(struct tcp_pcb *pcb, HttpConn *conn) {
    send_response(pcb, conn, 404, "Not Found",
                  "text/plain", "Not Found", 9);
}

static void send_405(struct tcp_pcb *pcb, HttpConn *conn) {
    send_response(pcb, conn, 405, "Method Not Allowed",
                  "text/plain", "Method Not Allowed", 18);
}

// ── Route handlers ─────────────────────────────────────────────────────────

static void route_sensors(struct tcp_pcb *pcb, HttpConn *conn) {
    state_lock();
    SensorState s = g_state;
    state_unlock();

    int len = snprintf(g_body, sizeof(g_body),
        "{"
        "\"water\":%s,"
        "\"temp_c\":%.1f,"
        "\"humidity_pct\":%.1f,"
        "\"motion\":%s,"
        "\"co_ppm\":%u,"
        "\"alarm_active\":%s"
        "}",
        s.water_detected  ? "true" : "false",
        s.temperature_c,
        s.humidity_pct,
        s.motion_detected ? "true" : "false",
        s.co_ppm,
        s.alarm_active    ? "true" : "false"
    );

    send_json(pcb, conn, g_body, (size_t)len);
}

static void route_wifi(struct tcp_pcb *pcb, HttpConn *conn) {
    WifiStatus ws = wifi_get_status();

    int len = snprintf(g_body, sizeof(g_body),
        "{"
        "\"state\":\"%s\","
        "\"ip\":\"%s\","
        "\"rssi_dbm\":%d,"
        "\"reconnect_count\":%lu"
        "}",
        wifi_state_str(ws.state),
        ws.ip,
        ws.rssi_dbm,
        ws.reconnect_count
    );

    send_json(pcb, conn, g_body, (size_t)len);
}

static void route_alarm_get(struct tcp_pcb *pcb, HttpConn *conn) {
    // Read alarm state
    state_lock();
    bool alarm_active = g_state.alarm_active;
    state_unlock();

    AlarmLevel level   = alarm_current_level();
    bool       latched = g_alarm.water_latched ||
                         g_alarm.co_critical_latched;

    int len = snprintf(g_body, sizeof(g_body),
        "{"
        "\"level\":\"%s\","
        "\"active\":%s,"
        "\"latched\":%s,"
        "\"water_latched\":%s,"
        "\"co_critical_latched\":%s,"
        "\"relay_active\":%s"
        "}",
        alarm_level_str(level),
        alarm_active              ? "true" : "false",
        latched                   ? "true" : "false",
        g_alarm.water_latched     ? "true" : "false",
        g_alarm.co_critical_latched ? "true" : "false",
        g_alarm.relay_active      ? "true" : "false"
    );

    send_json(pcb, conn, g_body, (size_t)len);
}

static void route_alarm_ack(struct tcp_pcb *pcb, HttpConn *conn,
                            const char *request) {
    // Only accept POST
    if (strncmp(request, "POST", 4) != 0) {
        send_405(pcb, conn);
        return;
    }

    alarm_acknowledge();

    AlarmLevel post_level = alarm_current_level();
    int len = snprintf(g_body, sizeof(g_body),
        "{"
        "\"acknowledged\":true,"
        "\"level\":\"%s\""
        "}",
        alarm_level_str(post_level)
    );

    send_json(pcb, conn, g_body, (size_t)len);
}

static void route_health(struct tcp_pcb *pcb, HttpConn *conn) {
    send_text(pcb, conn, "OK");
}

static void route_metrics(struct tcp_pcb *pcb, HttpConn *conn) {
    // Prometheus-style plaintext metrics.
    // Compatible with node_exporter text format — push gateway or
    // scrape directly with prometheus.yml static_configs.
    state_lock();
    SensorState s = g_state;
    state_unlock();

    WifiStatus ws    = wifi_get_status();
    AlarmLevel level = alarm_current_level();

    int len = snprintf(g_body, sizeof(g_body),
        "# HELP basement_water_detected Water sensor state\n"
        "# TYPE basement_water_detected gauge\n"
        "basement_water_detected %d\n"
        "\n"
        "# HELP basement_temperature_celsius Temperature in Celsius\n"
        "# TYPE basement_temperature_celsius gauge\n"
        "basement_temperature_celsius %.2f\n"
        "\n"
        "# HELP basement_humidity_percent Relative humidity percent\n"
        "# TYPE basement_humidity_percent gauge\n"
        "basement_humidity_percent %.2f\n"
        "\n"
        "# HELP basement_motion_detected PIR motion sensor state\n"
        "# TYPE basement_motion_detected gauge\n"
        "basement_motion_detected %d\n"
        "\n"
        "# HELP basement_co_ppm Carbon monoxide PPM\n"
        "# TYPE basement_co_ppm gauge\n"
        "basement_co_ppm %u\n"
        "\n"
        "# HELP basement_alarm_level Alarm severity (0=none 1=advisory 2=warning 3=critical)\n"
        "# TYPE basement_alarm_level gauge\n"
        "basement_alarm_level %d\n"
        "\n"
        "# HELP basement_wifi_rssi_dbm WiFi signal strength dBm\n"
        "# TYPE basement_wifi_rssi_dbm gauge\n"
        "basement_wifi_rssi_dbm %d\n"
        "\n"
        "# HELP basement_wifi_reconnects Total WiFi reconnection count\n"
        "# TYPE basement_wifi_reconnects counter\n"
        "basement_wifi_reconnects %lu\n",
        s.water_detected  ? 1 : 0,
        s.temperature_c,
        s.humidity_pct,
        s.motion_detected ? 1 : 0,
        s.co_ppm,
        (int)level,
        ws.rssi_dbm,
        ws.reconnect_count
    );

    send_response(pcb, conn, 200, "OK",
                  "text/plain; version=0.0.4",
                  g_body, (size_t)len);
}

static void route_dashboard(struct tcp_pcb *pcb, HttpConn *conn) {
    state_lock();
    SensorState s = g_state;
    state_unlock();

    WifiStatus ws    = wifi_get_status();
    AlarmLevel level = alarm_current_level();

    const char *water_class  = s.water_detected  ? "alert"  : "";
    const char *water_color  = s.water_detected  ? "danger" : "ok";
    const char *water_text   = s.water_detected  ? "WATER DETECTED" : "Dry";
    const char *alarm_color  = s.alarm_active    ? "danger" : "ok";
    const char *alarm_text   = alarm_level_str(level);
    const char *co_color     = s.co_ppm >= 50    ? "warn"   : "ok";
    const char *motion_text  = s.motion_detected ? "Detected" : "Clear";

    int len = snprintf(g_body, sizeof(g_body),
        "<!DOCTYPE html>\n"
        "<html lang=\"en\">\n"
        "<head>\n"
        "  <meta charset=\"UTF-8\">\n"
        "  <meta http-equiv=\"refresh\" content=\"3\">\n"
        "  <title>Basement Monitor</title>\n"
        "  <style>\n"
        "    body{font-family:system-ui;background:#0f1117;color:#e2e8f0;"
               "max-width:600px;margin:2rem auto;padding:1rem}\n"
        "    h1{color:#6c8ef5}\n"
        "    .card{background:#1a1d27;border-radius:8px;"
               "padding:1rem;margin:.5rem 0}\n"
        "    .alert{background:#7f1d1d;border:1px solid #ef4444}\n"
        "    .ok{color:#34d399}.warn{color:#fbbf24}\n"
        "    .danger{color:#ef4444;font-weight:bold}\n"
        "    a{color:#6c8ef5}\n"
        "  </style>\n"
        "</head>\n"
        "<body>\n"
        "  <h1>Basement Monitor</h1>\n"
        "  <div class=\"card %s\">\n"
        "    <b>Water:</b> <span class=\"%s\">%s</span>\n"
        "  </div>\n"
        "  <div class=\"card\">\n"
        "    <b>Temp:</b> %.1f&deg;C &nbsp; <b>Humidity:</b> %.1f%%\n"
        "  </div>\n"
        "  <div class=\"card\">\n"
        "    <b>Motion:</b> %s &nbsp;\n"
        "    <b>CO:</b> <span class=\"%s\">%u ppm</span>\n"
        "  </div>\n"
        "  <div class=\"card\">\n"
        "    <b>Alarm:</b> <span class=\"%s\">%s</span>\n"
        "    &nbsp;\n"
        "    <a href=\"/alarm/ack\" onclick=\""
               "fetch('/alarm/ack',{method:'POST'});"
               "return false;\">Acknowledge</a>\n"
        "  </div>\n"
        "  <div class=\"card\">\n"
        "    <b>WiFi:</b> %s &nbsp; <b>RSSI:</b> %ddBm"
               " &nbsp; <b>Reconnects:</b> %lu\n"
        "  </div>\n"
        "  <p style=\"color:#475569;font-size:.8rem\">\n"
        "    Auto-refresh 3s &middot;\n"
        "    <a href=\"/sensors\">JSON</a> &middot;\n"
        "    <a href=\"/metrics\">Metrics</a> &middot;\n"
        "    <a href=\"/health\">Health</a>\n"
        "  </p>\n"
        "</body>\n"
        "</html>",
        water_class, water_color, water_text,
        s.temperature_c, s.humidity_pct,
        motion_text, co_color, s.co_ppm,
        alarm_color, alarm_text,
        ws.ip, ws.rssi_dbm, ws.reconnect_count
    );

    send_html(pcb, conn, g_body, (size_t)len);
}

// ── Router ─────────────────────────────────────────────────────────────────

static void route_request(struct tcp_pcb *pcb, HttpConn *conn) {
    const char *req = (const char *)conn->req_buf;

    printf("[HTTP ] %.*s\n", 60, req); // log first 60 chars of request

    if (strstr(req, " /sensors"))        route_sensors(pcb, conn);
    else if (strstr(req, " /wifi"))      route_wifi(pcb, conn);
    else if (strstr(req, " /alarm/ack")) route_alarm_ack(pcb, conn, req);
    else if (strstr(req, " /alarm"))     route_alarm_get(pcb, conn);
    else if (strstr(req, " /metrics"))   route_metrics(pcb, conn);
    else if (strstr(req, " /health"))    route_health(pcb, conn);
    else if (strstr(req, " /"))          route_dashboard(pcb, conn);
    else                                 send_404(pcb, conn);
}

// ── lwIP callbacks ─────────────────────────────────────────────────────────

static void conn_close(HttpConn *conn) {
    if (!conn || conn->closed) return;
    conn->closed = true;

    if (conn->pcb) {
        tcp_arg(conn->pcb,  NULL);
        tcp_recv(conn->pcb, NULL);
        tcp_err(conn->pcb,  NULL);
        tcp_sent(conn->pcb, NULL);
        tcp_close(conn->pcb);
        conn->pcb = NULL;
    }

    conn_free(conn);
}

static err_t on_recv(void *arg, struct tcp_pcb *pcb,
                     struct pbuf *p, err_t err) {
    HttpConn *conn = (HttpConn *)arg;

    if (!conn || err != ERR_OK || !p) {
        if (p) pbuf_free(p);
        if (conn) conn_close(conn);
        return ERR_OK;
    }

    // Buffer incoming data — request may arrive in multiple chunks
    uint16_t copy_len = p->len;
    if (conn->req_len + copy_len >= HTTP_REQUEST_MAX) {
        copy_len = HTTP_REQUEST_MAX - conn->req_len - 1;
    }

    if (copy_len > 0) {
        memcpy(conn->req_buf + conn->req_len, p->payload, copy_len);
        conn->req_len += copy_len;
        conn->req_buf[conn->req_len] = '\0';
    }

    tcp_recved(pcb, p->tot_len);
    pbuf_free(p);

    // Check if we have a complete HTTP request (ends with \r\n\r\n)
    if (strstr((char *)conn->req_buf, "\r\n\r\n") && !conn->responded) {
        route_request(pcb, conn);
        conn_close(conn);
    }

    return ERR_OK;
}

static err_t on_accept(void *arg, struct tcp_pcb *newpcb, err_t err) {
    if (err != ERR_OK || !newpcb) return ERR_VAL;

    // Enforce concurrent connection limit
    if (g_active_connections >= HTTP_MAX_CONNECTIONS) {
        printf("[HTTP ] Connection limit reached (%d/%d) — rejecting\n",
               g_active_connections, HTTP_MAX_CONNECTIONS);
        tcp_abort(newpcb);
        return ERR_MEM;
    }

    HttpConn *conn = conn_alloc();
    if (!conn) {
        tcp_abort(newpcb);
        return ERR_MEM;
    }

    conn->pcb = newpcb;
    tcp_setprio(newpcb, TCP_PRIO_MIN);
    tcp_arg(newpcb,  conn);
    tcp_recv(newpcb, on_recv);
    tcp_err(newpcb,  on_error);
    tcp_sent(newpcb, on_sent);

    printf("[HTTP ] Client connected (%d/%d active)\n",
           g_active_connections, HTTP_MAX_CONNECTIONS);
    return ERR_OK;
}

static void on_error(void *arg, err_t err) {
    HttpConn *conn = (HttpConn *)arg;
    printf("[HTTP ] Connection error: %d\n", err);
    // lwIP has already freed the pcb on error — do not call tcp_close()
    if (conn) {
        conn->pcb    = NULL;
        conn->closed = true;
        conn_free(conn);
    }
}

static err_t on_sent(void *arg, struct tcp_pcb *pcb, u16_t len) {
    return ERR_OK;
}

// ── Public API ─────────────────────────────────────────────────────────────

void http_server_init(void) {
    struct tcp_pcb *pcb = tcp_new_ip_type(IPADDR_TYPE_ANY);
    if (!pcb) {
        printf("[HTTP ] Failed to allocate PCB\n");
        return;
    }

    if (tcp_bind(pcb, IP_ANY_TYPE, HTTP_PORT) != ERR_OK) {
        printf("[HTTP ] Failed to bind port %d\n", HTTP_PORT);
        tcp_abort(pcb);
        return;
    }

    g_listen_pcb = tcp_listen_with_backlog(pcb, HTTP_MAX_CONNECTIONS);
    if (!g_listen_pcb) {
        printf("[HTTP ] Failed to listen\n");
        tcp_abort(pcb);
        return;
    }

    tcp_accept(g_listen_pcb, on_accept);
    printf("[HTTP ] Listening on port %d (max %d connections)\n",
           HTTP_PORT, HTTP_MAX_CONNECTIONS);
}

void http_server_poll(void) {
    uint32_t now = to_ms_since_boot(get_absolute_time());

    // Check for timed-out connections
    for (int i = 0; i < HTTP_MAX_CONNECTIONS; i++) {
        if (!g_conn_used[i]) continue;
        HttpConn *conn = &g_conn_pool[i];
        if (conn->closed) continue;

        if (now - conn->open_time_ms > HTTP_TIMEOUT_MS) {
            printf("[HTTP ] Connection timed out — closing\n");
            conn_close(conn);
        }
    }
}

Rust `http.rs` Implementation

// src/http.rs
//
// HTTP/1.0 server for the basement monitor.
// Built on embassy-net TcpSocket.
//
// Routes:
//   GET  /          → HTML dashboard
//   GET  /sensors   → JSON sensor snapshot
//   GET  /wifi      → JSON WiFi status
//   GET  /alarm     → JSON alarm status
//   POST /alarm/ack → acknowledge latched alarm
//   GET  /health    → plaintext OK
//   GET  /metrics   → Prometheus plaintext
//   *               → 404
//
// Structural advantage over C:
//   Linear async code — accept, read, route, write in sequence.
//   No callbacks, no partial-read buffering state machine.
//   embassy-net handles partial reads — socket.read() fills the buffer.
//   Concurrent connection limit enforced by spawning N tasks at startup,
//   each with its own socket buffers — no runtime pool management.
//
// Structural advantage over TinyGo:
//   Zero heap allocation — heapless::String for all formatting.
//   Socket buffers are static — compiler verifies lifetimes.
//   embassy-net TcpSocket is async — read/write yield to other tasks.

use core::fmt::Write;

use embassy_net::{tcp::TcpSocket, Stack};
use embassy_time::{Duration, Timer, with_timeout};
use heapless::String;
use defmt::*;

use crate::{SensorState, STATE};
use crate::alarm::{AlarmLevel, ALARM_STATE};
use crate::wifi::WIFI_STATUS;

// ── Configuration ──────────────────────────────────────────────────────────
const HTTP_PORT:        u16      = 80;
const MAX_CONNECTIONS:  usize    = 3;
const REQUEST_TIMEOUT:  Duration = Duration::from_secs(10);
const REQUEST_BUF:      usize    = 512;
const BODY_BUF:         usize    = 2048;

// ── Static socket buffers ──────────────────────────────────────────────────
// Each connection task gets its own static RX/TX buffers.
// Static lifetime means the compiler verifies these outlive their socket.
// C equivalent: g_conn_pool with per-conn req_buf.
// TinyGo: make([]byte, 512) per connection — heap allocated.

macro_rules! make_socket_buffers {
    ($n:expr) => {{
        static mut RX: [u8; REQUEST_BUF] = [0u8; REQUEST_BUF];
        static mut TX: [u8; BODY_BUF]   = [0u8; BODY_BUF];
        unsafe { (&mut RX, &mut TX) }
    }};
}

// ── Server task ────────────────────────────────────────────────────────────
// Spawned from main.rs after WiFi connects.
// Spawns MAX_CONNECTIONS worker tasks, each accepting one connection
// at a time. This is the embedded equivalent of a fixed thread pool —
// and directly analogous to your room.WaitingRoom with a cap of 3.

#[embassy_executor::task]
pub async fn server_task(
    stack:   &'static Stack<cyw43::NetDriver<'static>>,
    spawner: embassy_executor::Spawner,
) {
    // Wait for network stack to be ready
    loop {
        if stack.is_link_up() { break; }
        Timer::after(Duration::from_millis(500)).await;
    }

    info!("HTTP server starting on port {}", HTTP_PORT);

    // Spawn one connection handler per allowed concurrent connection.
    // Each handler loops forever: accept → handle → close → repeat.
    // This statically bounds memory use — no dynamic allocation ever.
    spawner.spawn(connection_task(stack, 0)).unwrap();
    spawner.spawn(connection_task(stack, 1)).unwrap();
    spawner.spawn(connection_task(stack, 2)).unwrap();
}

// ── Connection handler task ────────────────────────────────────────────────
// One instance per allowed concurrent connection.
// id: 0, 1, 2 — used to select pre-allocated static buffers.
//
// The loop here is the async equivalent of C's on_accept() callback
// and TinyGo's for { conn, _ := ln.Accept(); go handleConn(conn) }.
// But linear — no callback registration, no goroutine spawning.

#[embassy_executor::task(pool_size = 3)]
async fn connection_task(
    stack: &'static Stack<cyw43::NetDriver<'static>>,
    id:    usize,
) {
    // Each task owns its buffers for its entire lifetime.
    // Rust's borrow checker proves no other task can access these.
    let mut rx_buf = [0u8; REQUEST_BUF];
    let mut tx_buf = [0u8; BODY_BUF];

    loop {
        let mut socket = TcpSocket::new(stack, &mut rx_buf, &mut tx_buf);
        socket.set_timeout(Some(REQUEST_TIMEOUT));

        // accept() suspends until a client connects.
        // Other tasks (sensors, display, alarm, other connection tasks)
        // run freely during this wait.
        if let Err(e) = socket.accept(HTTP_PORT).await {
            warn!("[HTTP/{}] Accept error: {}", id, e);
            Timer::after(Duration::from_millis(100)).await;
            continue;
        }

        info!("[HTTP/{}] Client connected", id);

        // Handle with timeout — close if client takes too long
        match with_timeout(REQUEST_TIMEOUT, handle_request(&mut socket)).await {
            Ok(())    => {}
            Err(_)    => warn!("[HTTP/{}] Request timed out", id),
        }

        socket.close();
        Timer::after(Duration::from_millis(10)).await;
    }
}

// ── Request handler ────────────────────────────────────────────────────────

async fn handle_request(socket: &mut TcpSocket<'_>) {
    let mut req_buf = [0u8; REQUEST_BUF];

    // Read request — embassy-net handles partial reads internally.
    // C's on_recv() may be called multiple times for one request.
    // Here: one .await, socket fills the buffer.
    let n = match socket.read(&mut req_buf).await {
        Ok(0) | Err(_) => return,
        Ok(n)          => n,
    };

    let request = core::str::from_utf8(&req_buf[..n]).unwrap_or("");
    info!("[HTTP ] {:.60}", request);

    // Route
    if      request.contains(" /sensors")    { serve_sensors(socket).await }
    else if request.contains(" /wifi")       { serve_wifi(socket).await }
    else if request.contains(" /alarm/ack")  { serve_alarm_ack(socket, request).await }
    else if request.contains(" /alarm")      { serve_alarm(socket).await }
    else if request.contains(" /metrics")    { serve_metrics(socket).await }
    else if request.contains(" /health")     { serve_health(socket).await }
    else if request.contains(" /")           { serve_dashboard(socket).await }
    else                                     { serve_404(socket).await }
}

// ── Response helper ────────────────────────────────────────────────────────

async fn send_response(
    socket:       &mut TcpSocket<'_>,
    status:       u16,
    status_text:  &str,
    content_type: &str,
    body:         &str,
) {
    let mut headers: String<256> = String::new();
    write!(headers,
        "HTTP/1.0 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\n\
         Connection: close\r\nAccess-Control-Allow-Origin: *\r\n\
         Cache-Control: no-cache\r\n\r\n",
        status, status_text, content_type, body.len()
    ).ok();

    socket.write_all(headers.as_bytes()).await.ok();
    socket.write_all(body.as_bytes()).await.ok();
}

// ── Route handlers ─────────────────────────────────────────────────────────

async fn serve_sensors(socket: &mut TcpSocket<'_>) {
    let s = STATE.lock().await.clone();
    let mut body: String<256> = String::new();

    write!(body,
        "{{\"water\":{water},\"temp_c\":{temp:.1},\
         \"humidity_pct\":{hum:.1},\"motion\":{motion},\
         \"co_ppm\":{co},\"alarm_active\":{alarm}}}",
        water  = s.water_detected,
        temp   = s.temperature_c,
        hum    = s.humidity_pct,
        motion = s.motion_detected,
        co     = s.co_ppm,
        alarm  = s.alarm_active,
    ).ok();

    send_response(socket, 200, "OK",
        "application/json", body.as_str()).await;
}

async fn serve_wifi(socket: &mut TcpSocket<'_>) {
    let ws = WIFI_STATUS.lock().await.clone();
    let mut body: String<256> = String::new();

    write!(body,
        "{{\"state\":\"{state}\",\"ip\":\"{ip}\",\
         \"rssi_dbm\":{rssi},\"reconnect_count\":{rc}}}",
        state = ws.state.label(),
        ip    = ws.ip.as_str(),
        rssi  = ws.rssi_dbm,
        rc    = ws.reconnect_count,
    ).ok();

    send_response(socket, 200, "OK",
        "application/json", body.as_str()).await;
}

async fn serve_alarm(socket: &mut TcpSocket<'_>) {
    let alarm = ALARM_STATE.lock().await.clone();
    let s     = STATE.lock().await.clone();
    let mut body: String<256> = String::new();

    write!(body,
        "{{\"level\":\"{level}\",\"active\":{active},\
         \"latched\":{latched},\"water_latched\":{wl},\
         \"co_critical_latched\":{cl},\"relay_active\":{relay}}}",
        level  = alarm.level.label(),
        active = s.alarm_active,
        latched = alarm.water_latched || alarm.co_crit_latched,
        wl     = alarm.water_latched,
        cl     = alarm.co_crit_latched,
        relay  = alarm.relay_active,
    ).ok();

    send_response(socket, 200, "OK",
        "application/json", body.as_str()).await;
}

async fn serve_alarm_ack(socket: &mut TcpSocket<'_>, request: &str) {
    if !request.starts_with("POST") {
        send_response(socket, 405, "Method Not Allowed",
            "text/plain", "Method Not Allowed").await;
        return;
    }

    // Signal the alarm task to acknowledge.
    // We use a static AtomicBool rather than a channel to avoid
    // needing an async channel between tasks.
    crate::alarm::request_acknowledge();

    // Brief wait for alarm task to process the acknowledge
    Timer::after(Duration::from_millis(50)).await;

    let alarm = ALARM_STATE.lock().await.clone();
    let mut body: String<128> = String::new();
    write!(body,
        "{{\"acknowledged\":true,\"level\":\"{}\"}}",
        alarm.level.label()
    ).ok();

    send_response(socket, 200, "OK",
        "application/json", body.as_str()).await;
}

async fn serve_health(socket: &mut TcpSocket<'_>) {
    send_response(socket, 200, "OK", "text/plain", "OK").await;
}

async fn serve_metrics(socket: &mut TcpSocket<'_>) {
    let s     = STATE.lock().await.clone();
    let ws    = WIFI_STATUS.lock().await.clone();
    let alarm = ALARM_STATE.lock().await.clone();

    let mut body: String<BODY_BUF> = String::new();

    write!(body,
        "# TYPE basement_water_detected gauge\n\
         basement_water_detected {water}\n\
         # TYPE basement_temperature_celsius gauge\n\
         basement_temperature_celsius {temp:.2}\n\
         # TYPE basement_humidity_percent gauge\n\
         basement_humidity_percent {hum:.2}\n\
         # TYPE basement_motion_detected gauge\n\
         basement_motion_detected {motion}\n\
         # TYPE basement_co_ppm gauge\n\
         basement_co_ppm {co}\n\
         # TYPE basement_alarm_level gauge\n\
         basement_alarm_level {alarm_lvl}\n\
         # TYPE basement_wifi_rssi_dbm gauge\n\
         basement_wifi_rssi_dbm {rssi}\n\
         # TYPE basement_wifi_reconnects counter\n\
         basement_wifi_reconnects {rc}\n",
        water     = s.water_detected as u8,
        temp      = s.temperature_c,
        hum       = s.humidity_pct,
        motion    = s.motion_detected as u8,
        co        = s.co_ppm,
        alarm_lvl = alarm.level as u8,
        rssi      = ws.rssi_dbm,
        rc        = ws.reconnect_count,
    ).ok();

    send_response(socket, 200, "OK",
        "text/plain; version=0.0.4", body.as_str()).await;
}

async fn serve_dashboard(socket: &mut TcpSocket<'_>) {
    let s     = STATE.lock().await.clone();
    let ws    = WIFI_STATUS.lock().await.clone();
    let alarm = ALARM_STATE.lock().await.clone();

    let water_class = if s.water_detected { "alert"  } else { "" };
    let water_color = if s.water_detected { "danger" } else { "ok" };
    let water_text  = if s.water_detected { "WATER DETECTED" } else { "Dry" };
    let alarm_color = if s.alarm_active   { "danger" } else { "ok" };
    let co_color    = if s.co_ppm >= 50   { "warn"   } else { "ok" };
    let motion_text = if s.motion_detected { "Detected" } else { "Clear" };

    let mut body: String<BODY_BUF> = String::new();

    write!(body,
        "<!DOCTYPE html>\
        <html lang=\"en\">\
        <head>\
          <meta charset=\"UTF-8\">\
          <meta http-equiv=\"refresh\" content=\"3\">\
          <title>Basement Monitor</title>\
          <style>\
            body{{font-family:system-ui;background:#0f1117;color:#e2e8f0;\
                  max-width:600px;margin:2rem auto;padding:1rem}}\
            h1{{color:#6c8ef5}}\
            .card{{background:#1a1d27;border-radius:8px;\
                   padding:1rem;margin:.5rem 0}}\
            .alert{{background:#7f1d1d;border:1px solid #ef4444}}\
            .ok{{color:#34d399}}.warn{{color:#fbbf24}}\
            .danger{{color:#ef4444;font-weight:bold}}\
            a{{color:#6c8ef5}}\
          </style>\
        </head>\
        <body>\
          <h1>Basement Monitor</h1>\
          <div class=\"card {wc}\">\
            <b>Water:</b> <span class=\"{wcol}\">{wtext}</span>\
          </div>\
          <div class=\"card\">\
            <b>Temp:</b> {temp:.1}&deg;C &nbsp;\
            <b>Humidity:</b> {hum:.1}%\
          </div>\
          <div class=\"card\">\
            <b>Motion:</b> {motion} &nbsp;\
            <b>CO:</b> <span class=\"{cocol}\">{co} ppm</span>\
          </div>\
          <div class=\"card\">\
            <b>Alarm:</b> <span class=\"{acol}\">{alvl}</span>\
            &nbsp;\
            <a href=\"#\" onclick=\"\
              fetch('/alarm/ack',{{method:'POST'}});\
              return false;\">Acknowledge</a>\
          </div>\
          <div class=\"card\">\
            <b>WiFi:</b> {ip} &nbsp;\
            <b>RSSI:</b> {rssi}dBm &nbsp;\
            <b>Reconnects:</b> {rc}\
          </div>\
          <p style=\"color:#475569;font-size:.8rem\">\
            Auto-refresh 3s &middot;\
            <a href=\"/sensors\">JSON</a> &middot;\
            <a href=\"/metrics\">Metrics</a> &middot;\
            <a href=\"/health\">Health</a>\
          </p>\
        </body>\
        </html>",
        wc     = water_class,
        wcol   = water_color,
        wtext  = water_text,
        temp   = s.temperature_c,
        hum    = s.humidity_pct,
        motion = motion_text,
        cocol  = co_color,
        co     = s.co_ppm,
        acol   = alarm_color,
        alvl   = alarm.level.label(),
        ip     = ws.ip.as_str(),
        rssi   = ws.rssi_dbm,
        rc     = ws.reconnect_count,
    ).ok();

    send_response(socket, 200, "OK",
        "text/html; charset=utf-8", body.as_str()).await;
}

async fn serve_404(socket: &mut TcpSocket<'_>) {
    send_response(socket, 404, "Not Found",
        "text/plain", "Not Found").await;
}

Why Rust Wins the Embedded Systems Battle — And Why C Finally Lost the Argument

A Staff Engineer's Conclusion After Building the Same System Three Times

There is a conversation happening in embedded systems engineering that has
been building for a decade and has finally reached a tipping point. The
question is not whether Rust is viable for microcontroller development —
that debate is settled. The question is whether the embedded C community
is ready to honestly reckon with what C has been costing us all along.

This article is the result of building the same basement monitoring system
— water detection, temperature, humidity, CO sensing, PIR motion, SSD1306
OLED display, WiFi, and an HTTP server — three times, in three languages,
on a Raspberry Pi Pico W. The three implementations were built in parallel,
file by file, module by module, so that every architectural decision could
be compared directly across C, TinyGo, and Rust/Embassy. The conclusion
was not predetermined. It emerged from the code itself.

What Was Built

The system is not a toy. It is a production-grade embedded application
with real operational requirements:

Six sensor inputs with different polling cadences and severity models
A four-level alarm system with latching, acknowledgement, and relay control
A two-page rotating OLED display with pixel-level rendering
WiFi with exponential backoff retry and automatic reconnection
An HTTP server with seven routes including Prometheus metrics
All of it running concurrently on a single microcontroller with 264KB of RAM and no operating system

Every module was implemented fully in all three languages: sensors,
display, alarm, wifi, and http. The Makefiles were written. The
comparison table was filled in from actual code, not from documentation
or benchmarks. When a claim was made about memory safety or concurrency,
there was a specific file and a specific line number behind it.

Why C Loses

C does not lose because it is slow. C does not lose because it cannot do
the job. C has been doing this job reliably for forty years and the
embedded systems running the world's infrastructure prove it. C loses for
a more uncomfortable reason: everything C gets right, it gets right
because of the engineer, not because of the language.

Consider the alarm module. The C implementation requires:

volatile SensorState g_state — the volatile keyword prevents the
compiler from optimizing away reads, but it does not prevent a data
race. That protection comes from critical_section_enter_blocking()
called correctly, every time, by every function that touches g_state.
The compiler does not verify this. The linker does not verify this. The
test suite may not catch it. Only code review and discipline stand
between correct behavior and a silent race condition.
alarm_acknowledge() writes directly to g_alarm — a global struct
accessible to any translation unit that includes alarm.h. Nothing in
the language prevents http.c from reading g_alarm.water_latched
without locking. The header file is not a contract. It is an invitation.
conn_close() calls free() — and if it is called twice, the behavior
is undefined. Not an error. Not a crash you can debug. Undefined. The
program may continue running with corrupted heap state for hours before
anything visibly wrong happens, and by then the audit trail is gone.
The SSD1306 font table is 576 bytes of hand-curated hexadecimal embedded
in display.c. It is correct. It took time to write and verify. It will
never be wrong in a way the compiler notices, because the compiler does
not know what a font table is supposed to contain.

None of these are criticisms of bad engineering. They are descriptions of
what correct, careful, professional embedded C looks like. The discipline
required to write safe embedded C is real, hard-won, and — critically —
invisible to the toolchain. It lives in the engineer's head. When that
engineer leaves the team, some of it leaves with them.

This is what C costs. Not performance. Not capability. Institutional
knowledge that cannot be mechanically verified.

At scale — at the level of teams, products, and decades — that cost
compounds. The engineers who built network infrastructure in C in the
1990s were excellent engineers. The reason that infrastructure is still
running is not that C protected it. It is that those engineers protected
it, and then their successors protected it, in an unbroken chain of human
discipline that has to be re-established every time the team changes.

Why Rust Wins

Rust wins for a reason that sounds simple and has profound implications:
Rust encodes forty years of embedded C wisdom into the compiler.

Every rule that experienced embedded engineers know — never share a
peripheral between two contexts, always check buffer sizes, always
initialize state before use, always release resources exactly once — Rust
enforces mechanically, before the binary is built, at zero runtime cost.

The alarm module in Rust demonstrates this concretely. PIN_8 — the
buzzer pin — is moved into alarm_task at construction. Not passed by
pointer. Not referenced externally. Moved. The type system records this
transfer of ownership. Any other code attempting to construct another
output using PIN_8 will not compile. The exclusivity guarantee that C
enforces by convention — "only alarm.c drives the buzzer" — Rust enforces
by construction. The convention becomes a proof.

STATE: Mutex<CriticalSectionRawMutex, SensorState> — the shared sensor
state — cannot be read without calling .lock().await. This is not a
runtime check. It is a type-level constraint. The compiler will not produce
a binary in which g_state is accessed without holding the lock, because
there is no syntax in Rust that expresses "read STATE without locking."
The operation does not exist in the type system.

heapless::String<24> — used throughout the display and HTTP modules —
has a compile-time capacity. Writing more than 24 characters returns Err.
It cannot overflow silently. It cannot corrupt adjacent stack memory. The
class of bug that has caused security vulnerabilities in embedded C systems
for thirty years — the buffer overrun — is not a runtime check in Rust.
It is a type boundary that the compiler enforces at every callsite.

The HTTP server runs three concurrent connection handlers as
#[embassy_executor::task(pool_size=3)]. The memory for all three is
allocated statically. The compiler verifies that the socket buffers outlive
the tasks that use them. There is no malloc(). There is no free().
There is no possibility of a use-after-free because the lifetime of every
allocation is part of the type signature, visible to the compiler, verified
before the binary is linked.

And critically — all of this safety costs nothing at runtime. The binary
is comparable in size to the C implementation. The execution speed is
equivalent. The GC does not exist. The runtime overhead of the safety
guarantees is exactly zero, because the guarantees are compile-time
properties, not runtime checks.

Why TinyGo Is Honest About Its Position

TinyGo deserves respect for what it is and candor about what it is not.

What it is: the fastest path from a Go developer's existing mental
model to working embedded firmware. The goroutine model, the defer
cleanup, the standard net package — these are not approximations of Go.
They are Go, running on bare metal, with a stripped runtime. For a Go
developer who wants to write embedded code without learning a new language,
TinyGo is genuinely the right starting point. The alarm module's pulse
loop in TinyGo reads exactly like the intended behavior:

buzzerPin.High()
time.Sleep(criticalOn)
buzzerPin.Low()
time.Sleep(criticalOff)

in a way that C's timestamp-polling state machine never does.

What it is not: a zero-cost abstraction layer. fmt.Sprintf allocates
on every call. The garbage collector runs. On a device with 264KB of RAM,
the GC pauses are brief and infrequent enough to be invisible at
human-interaction timescales. But they are real, and they are
non-deterministic, and in a system where the alarm task needs to pulse a
buzzer at exactly 200ms intervals, non-deterministic pauses are a
correctness concern, not just a performance concern.

TinyGo also does not solve the ownership problem. Two goroutines can
configure the same pin. The scheduler enforces nothing about hardware
exclusivity — only the programmer does. This is safer than C's global
state model because the goroutine structure at least makes the concurrency
visible. But it is less safe than Rust's ownership model because the
compiler does not verify it.

TinyGo's honest position in the hierarchy is: better than C for
readability, better than C for concurrency structure, worse than Rust for
safety guarantees, worse than Rust for determinism. For prototyping and
experimentation it is excellent. For unattended production firmware it
introduces risks that Rust eliminates.

The Benchmark That Actually Matters

The embedded systems community is accustomed to benchmarking languages on
execution speed and binary size. Those benchmarks favor C and Rust
approximately equally and leave TinyGo somewhat behind due to GC overhead.
They are not the benchmark that matters for this class of system.

The benchmark that matters is: what happens when the system has been
running unattended for six months and a sensor fires at 3am?

In C, the answer depends on whether every critical_section_enter was
paired with a critical_section_exit, whether every free() was called
exactly once, whether the volatile qualifiers are in the right places,
and whether the engineer who wrote the alarm module six months ago
remembered to handle the case where water clears before the HTTP
acknowledge arrives. The compiler cannot answer any of these questions.
Only running the code in the conditions that trigger the bug can answer
them, and by then it may be too late.

In Rust, the compiler answered most of these questions before the binary
was built. The peripheral ownership is proven. The buffer bounds are
enforced. The state access is synchronized. The resource cleanup is
automatic. What remains — the application logic, the threshold values,
the alarm escalation policy — is the part that requires human judgment,
and Rust makes no claim to automate that. But the class of bugs that
emerge from implementation errors rather than design errors — the class
that has driven embedded systems recalls, security patches, and midnight
incident responses for decades — Rust eliminates before the first byte
is flashed.

The Full Comparison

Dimension	C	TinyGo	Rust/Embassy
Concurrency model	Manual poll loop, no true concurrency	Real goroutines, cooperative scheduler	Async tasks, cooperative, interrupt-driven
DHT22 timing	Busy-wait, blocks CPU entirely	Busy-wait in goroutine, others run	PIO hardware offload, CPU completely free
State sharing	`volatile` + `critical_section`, convention only	`sync.Mutex`, convention only	`Mutex<T>`, compiler enforced
Memory safety	`char[N]`, silent overflow = UB	`make([]byte,n)` + GC	`heapless::String`, overflow = compile error
HTTP server	lwIP raw callbacks, 4 callback functions	`net.Listen` + goroutine/conn	`embassy-net` TcpSocket, linear async code
Cleanup / resource mgmt	Manual `free()`, easy to forget	`defer conn.Close()`, automatic	Drop trait, automatic, enforced
Pin safety	Convention only	Convention only	Compile-time ownership proof
Binary size	Smallest ~50KB	Medium ~200–400KB	Small ~80–150KB
GC pauses	None	Yes, brief on allocations	None
WiFi connect	Blocks CPU entirely	Blocks goroutine, others run	Fully async, yields executor
Driver ecosystem	Mature, large C libs	`tinygo/x/drivers`, growing	`embedded-hal` crates, mature
Readable code	Medium (callbacks)	Highest (goroutines)	High (async/await)
Production maturity	Proven, decades	Growing, 2–3 years Pico W	Growing fast, 2–3 years Pico W

Medal Count Across 12 Dimensions

Language	Gold	Silver	Bronze
Rust/Embassy	9	2	0
TinyGo	4	5	2
C	2	1	9

On the Collaboration That Produced This Conclusion

This analysis was produced through an extended technical collaboration
between a staff-level engineer with professional experience at Cisco
Systems, Oracle America, and Warner Bros. Games — and Claude, Anthropic's
AI system.

The engineer brought production systems experience, embedded hardware
familiarity from university circuit design coursework, and the
architectural instincts developed across two decades of building software
that has to work when nobody is watching. This is the same engineer who
built room — a FIFO waiting
room middleware for Go and Gin that manages bounded concurrent admission
with lifecycle callbacks, skip-the-line payments, and VIP passes. The
patterns in room — bounded resources, snapshot state, controlled
admission — reappear directly in the embedded HTTP server, the alarm
module, and the sensor state management. The problems are the same at
every scale.

Claude brought the ability to hold three complete implementations in
parallel, compare them at the module level across thousands of lines of
code, and surface the specific file and line number behind every claim
in the comparison.

The conclusion — that Rust is the winner for production embedded systems,
that C retains value as an educational tool and for engineers with deep
existing discipline, and that TinyGo occupies an honest and useful middle
position — was not reached by reading documentation or running benchmarks.
It was reached by writing the same alarm module three times, the same
display driver three times, the same WiFi reconnection logic three times,
and asking at each step: where does this break, and who catches it
when it does?

In C, the engineer catches it — if they are still on the team, if the
conditions that trigger it occur during testing, if the code review
process has the bandwidth to find it.

In Rust, the compiler catches it — unconditionally, before the binary exists, every time.

That is why Rust wins.

The Practical Recommendation

For engineers evaluating languages for a new embedded project in 2026:

Use Rust if the system will run unattended, if correctness failures
have real-world consequences, if the team will change over time, or if
the firmware will be maintained for more than one product cycle. The
upfront investment in learning the ownership model and the embedded
ecosystem pays back in the form of bugs that never happen in the field.

Use TinyGo if the team is primarily Go developers, if the timeline
requires a working prototype quickly, or if the project is experimental
and the priority is iteration speed over production hardening. Plan to
evaluate Rust before production deployment.

Use C if the team has deep embedded C expertise and the discipline
to apply it consistently, if the target hardware is too constrained for
Rust's toolchain, or if the project exists primarily to understand what
the hardware is doing at the register level. C remains the best
educational tool for embedded systems because it hides nothing — but
hiding nothing requires the engineer to see everything, and that is a
requirement that scales with the engineer, not with the team.

Rust Decorators for Go Developers

Andrei Merlescu — Fri, 22 May 2026 18:34:06 +0000

In Go, most of these concerns are handled by conventions, comments, runtime reflection, and external tools. In Rust, they are expressed as attributes that the compiler reads, verifies, and enforces before your program ever runs.

If you have spent years writing Go, you already think in terms of goroutines, interfaces, and the implicit contract that the runtime handles the hard parts for you. Rust asks you to make all of those implicit contracts explicit — and the mechanism it uses to do that is attributes. Where Go relies on naming conventions, comments, build tags, struct tag strings, and external linters to express intent, Rust has a formal attribute syntax that the compiler reads at compile time, verifies, and enforces before a single line of your code runs. This document walks through thirteen categories of Rust attributes side by side with their closest Go analogs — not to argue that one language is better than the other, but to give you a map from the Go mental model you already own into the Rust one you are building. You will see that many things Go does silently behind its runtime — scheduling threads, copying memory, skipping serialized fields, enforcing interface contracts — Rust requires you to express openly through attributes, and in exchange the compiler guarantees correctness that Go leaves to discipline, convention, and luck. By the end you will understand not just what each attribute does, but why it exists and what problem it is solving that Go solves a different way.

`#[derive(...)]` — Automatic Trait Implementation

The Concept

#[derive(...)] tells the Rust compiler to automatically generate implementations of standard traits for your type. A trait in Rust is roughly what an interface is in Go, except the compiler can write the implementation for you when the logic is mechanical. Without #[derive(...)], you would have to manually implement Debug, Clone, PartialEq, and others for every struct and enum you write. The derive macro inspects your type at compile time and generates the boilerplate so you don’t have to.

The most commonly derived traits are: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default, and Serialize/Deserialize from serde.

// Go has no equivalent syntax. The closest analog is implementing
// an interface by satisfying its method signatures manually.
// Go generates nothing for you — you write it all yourself.

type Person struct {
    Name string
    Age  int
}

// To print with structure, you implement Stringer manually:
func (p Person) String() string {
    return fmt.Sprintf("Person{Name: %s, Age: %d}", p.Name, p.Age)
}

// To copy, Go structs are value types — assignment copies automatically.
// To compare, == works on structs if all fields are comparable.
// None of this is declared — it's implicit or manual.

Rust

// Rust generates all of this for you via #[derive(...)].
// Each trait listed is fully implemented by the compiler.

#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
struct Person {
    name: String,
    age: u32,
}

fn main() {
    let p1 = Person {
        name: "Andrei".to_string(),
        age: 40,
    };

    // Debug — enabled by #[derive(Debug)]
    // {:?} is the debug format, {:#?} is pretty-printed
    println!("{:?}", p1);
    println!("{:#?}", p1);

    // Clone — enabled by #[derive(Clone)]
    // .clone() performs a deep copy
    // Without this derive, .clone() does not compile
    let p2 = p1.clone();

    // PartialEq — enabled by #[derive(PartialEq)]
    // Without this, == does not compile on your struct
    assert_eq!(p1, p2);

    // Default — enabled by #[derive(Default)]
    // Returns a zero-value equivalent, like Go's zero value
    // String defaults to "", u32 defaults to 0
    let empty: Person = Person::default();
    println!("{:?}", empty);
}

// Copy vs Clone — critical distinction:
// Copy means the type can be duplicated by simply copying bits.
// Clone means the type knows how to duplicate itself, possibly with allocation.
// String cannot be Copy because it owns heap memory.
// u32, bool, f64 can be Copy because they are fixed-size stack values.

#[derive(Debug, Clone, Copy, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}
// Point is Copy, so assignment moves a copy, not ownership.
// You can use p after assigning it to another variable.

Key Concepts: If any field in your struct does not implement a trait you are trying to derive, the derive will fail to compile. For example, you cannot derive Copy on a struct that contains a String because String is not Copy. You cannot derive Eq without also deriving PartialEq. The order inside #[derive(...)] does not matter. You can stack multiple derives on the same line or split them across multiple #[derive(...)] attributes — both are valid. Deriving Default requires every field’s type to also implement Default.

`#[arg(...)]` — Clap CLI Argument Declaration

The Concept

#[arg(...)] is not a standard library attribute — it comes from the clap crate and decorates fields inside a #[derive(Parser)] struct. It describes how a struct field maps to a command-line argument: its flag name, short form, default value, environment variable fallback, help text, validation rules, and behavior. Clap reads these attributes at compile time and generates a full CLI parser from them.

// Go's closest analog is the flag package, but it is entirely manual.
// There is no struct-level declaration — you register each flag imperatively.
// There is no compile-time validation — wrong types fail at runtime.

import "flag"

var find = flag.String("find", "", "substring to search for")
var cores = flag.Int("cores", 0, "number of cores to use")
var insensitive = flag.Bool("insensitive", true, "case insensitive search")

func main() {
    flag.Parse()
    // Values are now available via *find, *cores, *insensitive
    // No env var fallback built in
    // No conflict detection
    // No required field enforcement
}

Rust

use clap::Parser;

#[derive(Parser, Debug)]
#[command(name = "find-xrp-addr", about = "XRP vanity address finder")]
struct Cli {

    // long:    creates --find flag
    // env:     falls back to $FIND if --find not passed
    // Type Option<String> means not required — None if absent
    #[arg(long, env = "FIND")]
    find: Option<String>,

    // long = "1p": overrides the field name for the CLI flag
    // action = SetTrue: presence of --1p sets this to true
    //                   without SetTrue, bool requires --1p=true explicitly
    // env: falls back to $USE_ONEPASSWORD
    #[arg(long = "1p", env = "USE_ONEPASSWORD", action = clap::ArgAction::SetTrue)]
    use_op: bool,

    // default_value_t: typed default, not a string — avoids parse step
    // 0 is sentinel meaning "use all available cores"
    #[arg(long, default_value_t = 0, env = "CORES")]
    cores: usize,

    // value_name: controls the placeholder in --help output
    // shows as: --begins <PREFIX>
    #[arg(long, value_name = "PREFIX", env = "BEGINS")]
    begins: Option<String>,

    // conflicts_with: errors if both --begins and --ends are
    // combined with --find in an unsupported way
    // requires: enforces another argument must also be present
    #[arg(long, env = "ENDS")]
    ends: Option<String>,

    // short and long together: accepts both -v and --vault
    #[arg(short, long, env = "VAULT")]
    vault: Option<String>,
}

fn main() {
    let cli = Cli::parse();
    println!("{:?}", cli);
}

Key Concepts: default_value takes a &str and parses it, so a wrong string panics at runtime. default_value_t takes a typed expression and fails at compile time if the type is wrong — always prefer default_value_t. action = clap::ArgAction::SetTrue is required on bool fields if you want flag presence alone to mean true. Without it, the user must write --flag=true explicitly. Option<String> means absent is None — do not use required = true on an Option unless you explicitly want to override that inference.

BONUS: I wrote rusty-figtree so that you can use my figtree pattern in Rust, _instead of using #[arg()].

`#[cfg(...)]` — Conditional Compilation

The Concept

#[cfg(...)] tells the compiler to include or exclude a block of code depending on compile-time conditions: the target operating system, architecture, feature flags, test mode, or custom cfg values. The excluded code is completely removed from the binary — it is never parsed beyond syntax checking. This is more powerful than a runtime flag and more integrated than a preprocessor macro.

// Go's closest analog is build tags — a comment at the top of a file
// that tells the Go toolchain whether to include that file.
// Go operates at the file level; Rust operates at the item level.

//go:build linux
// +build linux  (old syntax, kept for compatibility)

package main

// This entire file is excluded on non-Linux platforms.
// You cannot conditionally compile a single function inside a file in Go
// without splitting it into separate files.

func platformSpecificThing() {
    fmt.Println("Linux only")
}

Rust

// #[cfg(...)] operates at the item level — a single function,
// struct, impl block, or expression can be conditionally included.

// Target OS conditions
#[cfg(target_os = "linux")]
fn platform_message() {
    println!("Running on Linux");
}

#[cfg(target_os = "macos")]
fn platform_message() {
    println!("Running on macOS");
}

#[cfg(target_os = "windows")]
fn platform_message() {
    println!("Running on Windows");
}

// Target architecture
#[cfg(target_arch = "x86_64")]
fn arch_note() {
    println!("64-bit x86");
}

// Feature flags — enabled via Cargo.toml [features] or --features flag
// This function only exists if the crate was compiled with --features="json"
#[cfg(feature = "json")]
fn serialize_json() {
    // json-specific code here
}

// Test-only code — #[cfg(test)] blocks are excluded from release builds
// This is the standard pattern for unit tests in Rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }
}

// cfg! macro — evaluates to a bool at compile time for use in expressions
fn main() {
    if cfg!(debug_assertions) {
        println!("Running in debug mode");
    }

    // Combining conditions
    // all() = AND,  any() = OR,  not() = NOT
    #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
    println!("Linux on x86_64 only");

    #[cfg(any(target_os = "linux", target_os = "macos"))]
    println!("Linux or macOS");

    #[cfg(not(target_os = "windows"))]
    println!("Not Windows");
}

Key Concepts: Code inside a #[cfg(...)] block that is excluded is still syntax-checked but not type-checked in older Rust versions. In modern Rust it is fully excluded. This means you can have two functions with the same name under different #[cfg(...)] guards — this is the standard cross-platform pattern. The cfg!() macro is for runtime branching that the compiler still optimizes away. #[cfg(test)] is the canonical way to keep test helpers and unit tests out of production binaries — equivalent to Go's _test.go file convention but scoped to individual items rather than files.

`#[macro_export]` and `#[macro_use]` — Macro Visibility

The Concept

#[macro_export] makes a macro defined with macro_rules! publicly available to users of your crate, placing it at the crate root regardless of where in the module tree you defined it. #[macro_use] was the old way to import all macros from an external crate before Rust 2018 edition introduced use imports for macros. In modern Rust, #[macro_use] is mostly legacy but still seen in older codebases.

// Go has no macros and no equivalent concept.
// The closest analog is a package-level exported function —
// you make something public by capitalizing its name.

package mylib

// Exported — visible to importers
func MyHelper(s string) string {
    return strings.ToUpper(s)
}

// Unexported — private to this package
func myHelper(s string) string {
    return strings.ToLower(s)
}

// There is no way in Go to define something that generates code
// at compile time the way Rust macros do.
// go generate exists but it runs external tools, not inline code.

Rust

// Defining a macro and exporting it from your crate

// WITHOUT #[macro_export]:
// This macro is only usable within this module and its children.
macro_rules! say_hello {
    () => {
        println!("Hello");
    };
}

// WITH #[macro_export]:
// This macro is placed at the crate root and is importable by users
// of this crate with: use mycrate::greet;
#[macro_export]
macro_rules! greet {
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
    // Multiple arms — like match, first match wins
    ($name:expr, $greeting:expr) => {
        println!("{}, {}!", $greeting, $name);
    };
}

// In your own crate you can call it directly:
fn main() {
    greet!("Andrei");
    greet!("Andrei", "Good morning");
}

// ---

// #[macro_use] — OLD STYLE, pre-Rust-2018
// Importing all macros from an external crate without naming them:

#[macro_use]
extern crate serde_derive;

// Modern equivalent — explicit and preferred:
use serde::{Serialize, Deserialize};

// ---

// #[macro_use] on a module — imports all macros defined in that
// module into the parent scope. Still occasionally useful internally.

#[macro_use]
mod my_macros;
// Now all macros from my_macros are available in this module
// without qualifying them as my_macros::some_macro!(...)

Key Concepts: #[macro_export] always places the macro at the crate root, regardless of nesting depth. If your macro is inside src/utils/helpers.rs, importing it is still use mycrate::my_macro, not use mycrate::utils::helpers::my_macro. This surprises many developers. In Rust 2018 and later, prefer explicit use mycrate::my_macro over #[macro_use] extern crate mycrate. The #[macro_use] attribute on extern crate is considered legacy. Procedural macros (#[derive(...)], #[some_attr], and function-like my_macro!(...) implemented in proc-macro crates) are a separate, more powerful system from macro_rules! and do not use #[macro_export].

`#[repr(...)]` — Memory Layout Control

The Concept

#[repr(...)] controls how Rust lays out a struct or enum in memory. By default Rust makes no guarantees about field ordering or padding — it may reorder fields to optimize alignment. #[repr(C)] forces C-compatible layout, which is required for FFI. #[repr(u8)] and similar force an enum’s discriminant to a specific integer type. #[repr(transparent)] guarantees a single-field struct has the same layout as its inner type.

// Go structs have a defined layout: fields appear in declaration order,
// with padding inserted by the compiler for alignment.
// Go has no attribute to change this — you control layout by field order.

// Inefficient — bool causes padding before int64
type Bad struct {
    A bool    // 1 byte + 7 bytes padding
    B int64   // 8 bytes
}

// Efficient — largest fields first
type Good struct {
    B int64   // 8 bytes
    A bool    // 1 byte + 7 bytes padding at end
}

// For FFI with C, Go uses cgo and the layout matches C struct layout
// for exported types — but this is implicit, not declared.

Rust

// Default: Rust may reorder fields freely for optimal packing.
// No guarantees. Do not transmute or use in FFI without #[repr(C)].
struct DefaultLayout {
    a: u8,
    b: u64,
    c: u8,
}
// Rust may reorder this to: b(u64), a(u8), c(u8) + padding

// #[repr(C)]: fields in declaration order, C-compatible padding.
// Required for any struct passed across FFI boundaries.
#[repr(C)]
struct CCompatible {
    a: u8,      // 1 byte
    // 7 bytes padding
    b: u64,     // 8 bytes
    c: u8,      // 1 byte
    // 7 bytes padding
}

// #[repr(packed)]: removes ALL padding. Fields may be unaligned.
// Accessing unaligned fields is undefined behavior in C.
// In Rust, taking a reference to a packed field is an error.
#[repr(packed)]
struct Packed {
    a: u8,
    b: u64,  // unaligned — no padding before it
}

// #[repr(transparent)]: single-field struct has identical layout
// to its inner type. Used for newtype wrappers in FFI.
#[repr(transparent)]
struct Meters(f64);
// Meters and f64 are interchangeable at the ABI level.

// #[repr(u8)] on an enum: discriminant stored as u8
// Without this, Rust picks the discriminant size freely.
#[repr(u8)]
enum Direction {
    North = 0,
    South = 1,
    East  = 2,
    West  = 3,
}

// #[repr(C)] on an enum: C-compatible tagged union layout
#[repr(C)]
enum CEnum {
    A,
    B,
    C,
}

Key Concepts: Never use #[repr(packed)] unless you are parsing binary wire formats and know exactly what you are doing — unaligned access is undefined behavior on many architectures including ARM. #[repr(transparent)] is the correct way to build newtype wrappers for FFI — it guarantees the wrapper is a zero-cost abstraction with no layout difference from the inner type. #[repr(C)] is mandatory for any struct you pass to a C function via FFI. Forgetting it means Rust may reorder your fields and your C code reads garbage.

`#[non_exhaustive]` — Future-Proof Enums and Structs

The Concept

#[non_exhaustive] marks an enum or struct as potentially having more variants or fields added in future versions of the crate. External crates that match on a #[non_exhaustive] enum are required by the compiler to include a wildcard _ arm. This prevents downstream breakage when you add a new variant.

// Go has no equivalent. The closest analog is the convention of
// documenting that a type "may grow" and relying on developer discipline.

// In Go, switching on an iota enum with no default case compiles fine.
// Adding a new value silently breaks exhaustive switches — no warning.

type Direction int
const (
    North Direction = iota
    South
    East
    West
)

func describe(d Direction) string {
    switch d {
    case North:
        return "north"
    case South:
        return "south"
    // No East, West — compiles fine, silently returns ""
    // If you add Northeast tomorrow, nothing tells callers to update
    }
    return ""
}

Rust

// Without #[non_exhaustive]:
// External code that matches this enum must cover all variants.
// Adding a new variant is a breaking change.
pub enum Direction {
    North,
    South,
    East,
    West,
}

// With #[non_exhaustive]:
// External code MUST include a wildcard arm.
// You can add variants in future releases without breaking callers.
#[non_exhaustive]
pub enum Status {
    Active,
    Inactive,
    Pending,
    // You may add more variants in future versions.
}

// External crate trying to match Status:
fn describe(s: Status) -> &'static str {
    match s {
        Status::Active   => "active",
        Status::Inactive => "inactive",
        Status::Pending  => "pending",
        // This wildcard arm is REQUIRED by the compiler
        // because Status is #[non_exhaustive]
        _ => "unknown",
    }
}

// #[non_exhaustive] on a struct:
// External code cannot construct it with struct literal syntax.
// They must use your provided constructor functions.
#[non_exhaustive]
pub struct Config {
    pub timeout: u64,
    pub retries: u32,
    // You can add fields without breaking external callers
}

// External code cannot do this if Config is #[non_exhaustive]:
// let c = Config { timeout: 30, retries: 3 }; // compile error externally
// They must use: Config::new(30, 3) or a builder pattern

Key Concepts: #[non_exhaustive] only affects code outside the defining crate. Inside the crate that defines the type, exhaustive matching still works and struct literals are still valid. This is the correct attribute to use on any public enum in a library crate where you anticipate adding variants in future semver-compatible releases. Without it, adding a variant is a breaking change that requires a major version bump.

`#[must_use]` — Enforced Return Value Handling

The Concept

#[must_use] on a function or type tells the compiler to emit a warning if the return value is discarded. It is how Rust enforces that callers handle Result and other important values. Without this attribute, silently ignoring a Result compiles without warning — which is how silent error swallowing happens.

// Go's closest analog is the convention of always checking errors.
// The compiler does NOT warn you if you ignore a return value.
// Ignoring errors in Go is legal and silent.

os.Remove("file.txt")          // legal — error silently ignored
val, _ := strconv.Atoi("123") // legal — error explicitly discarded

// Go relies entirely on developer discipline and linters like errcheck.
// There is no language-level enforcement.

Rust

// #[must_use] on a type:
// Any function returning this type triggers a warning if result is dropped.
// This is already on Result and Option in the standard library.

#[must_use]
enum MyResult<T> {
    Ok(T),
    Err(String),
}

// #[must_use] on a function:
// Warning if the return value of THIS specific function is discarded.
#[must_use]
fn compute_checksum(data: &[u8]) -> u32 {
    data.iter().fold(0u32, |acc, &b| acc.wrapping_add(b as u32))
}

fn main() {
    // This triggers: warning: unused return value of `compute_checksum`
    compute_checksum(&[1, 2, 3]);

    // This is fine — value is used
    let checksum = compute_checksum(&[1, 2, 3]);
    println!("{}", checksum);

    // Explicitly discarding — suppresses the warning
    // Use this when you genuinely mean to ignore the value
    let _ = compute_checksum(&[1, 2, 3]);

    // Result is #[must_use] in stdlib — this warns:
    std::fs::remove_file("file.txt");

    // This is fine:
    let _ = std::fs::remove_file("file.txt"); // explicit discard
    std::fs::remove_file("file.txt").ok();    // .ok() converts to Option, discards
    std::fs::remove_file("file.txt").unwrap(); // panics on error
    std::fs::remove_file("file.txt").expect("failed to remove"); // panics with message
}

// #[must_use] with a message:
#[must_use = "this seed was generated at cost — handle the result"]
fn generate_seed() -> [u8; 32] {
    [0u8; 32] // placeholder
}

Key Concepts: Result<T, E> and Option<T> are both #[must_use] in the standard library. This is why the compiler warns you when you call a function returning Result and do nothing with it. The idiomatic ways to explicitly discard are let _ = ... for a one-off, or .ok() on a Result to convert it to an Option and implicitly drop it. Using #[must_use] on your own types and functions is considered good library hygiene — it prevents callers from making silent mistakes.

`#[inline]` — Inlining Hints

The Concept

#[inline] suggests to the compiler that a function’s body should be copied into every call site rather than generating a function call instruction. This eliminates call overhead and enables further optimizations at the call site. #[inline(always)] is a strong directive. #[inline(never)] prevents inlining, useful for debugging or code size control.

// Go's compiler inlines automatically and aggressively.
// You cannot annotate functions with inlining hints in Go.
// The closest you can do is use //go:noinline to prevent it.

//go:noinline
func doNotInline(x int) int {
    return x * 2
}

// Otherwise, Go decides entirely on its own.
// You can observe inlining decisions with: go build -gcflags="-m"

Rust

// #[inline] — hint to the compiler, may or may not be honored
// Most useful for small functions in library crates where the
// compiler cannot see across crate boundaries without LTO.
#[inline]
fn add(a: u32, b: u32) -> u32 {
    a + b
}

// #[inline(always)] — strong directive, almost always honored
// Use for hot path functions where call overhead is measurable.
// Overuse bloats binary size — every call site gets a copy.
#[inline(always)]
fn fast_clamp(val: f64, min: f64, max: f64) -> f64 {
    if val < min { min } else if val > max { max } else { val }
}

// #[inline(never)] — prevent inlining
// Useful when profiling — inlined functions disappear in stack traces.
// Also useful when a function is large and called from many places.
#[inline(never)]
fn expensive_operation(data: &[u8]) -> u64 {
    data.iter().map(|&b| b as u64).sum()
}

fn main() {
    let result = add(1, 2);       // likely inlined — no call instruction
    let clamped = fast_clamp(1.5, 0.0, 1.0);
    let sum = expensive_operation(&[1, 2, 3]);
    println!("{} {} {}", result, clamped, sum);
}

Key Concepts: #[inline] is most important for functions in library crates. Within a single binary, the compiler can inline freely using its own judgment. Across crate boundaries, the compiler cannot inline unless the function is marked #[inline] or link-time optimization (LTO) is enabled. For hot-path cryptographic or search code like your XRP seed generator, #[inline(always)] on your innermost loop helpers can produce measurable gains. Do not use it globally — measure first.

`#[test]` — Unit Test Declaration

The Concept

#[test] marks a function as a unit test. The function is only compiled when running cargo test and is excluded from release builds. Test functions take no arguments and return either () or Result<(), E>. Combined with #[cfg(test)] on a module, this is the complete built-in testing story in Rust.

// Go tests live in files ending in _test.go.
// Test functions start with Test and take *testing.T.
// The file is automatically excluded from non-test builds.

// file: mypackage_test.go
package mypackage

import "testing"

func TestAdd(t *testing.T) {
    result := add(1, 2)
    if result != 3 {
        t.Errorf("expected 3, got %d", result)
    }
}

// Subtests:
func TestMath(t *testing.T) {
    t.Run("addition", func(t *testing.T) {
        // ...
    })
    t.Run("subtraction", func(t *testing.T) {
        // ...
    })
}

Rust

// Production code lives here — in the same file as tests.
fn add(a: u32, b: u32) -> u32 {
    a + b
}

// #[cfg(test)] means this entire module is excluded from non-test builds.
// It can see private functions in the parent module — tests are siblings,
// not external callers. This is different from Go where _test.go files
// can be in the same package (white-box) or a separate _test package (black-box).
#[cfg(test)]
mod tests {
    use super::*; // bring parent module's items into scope

    // #[test] marks this as a test function
    // cargo test discovers and runs all #[test] functions
    #[test]
    fn test_add() {
        assert_eq!(add(1, 2), 3);
    }

    // Tests can return Result — if Err is returned, the test fails
    #[test]
    fn test_with_result() -> Result<(), String> {
        let val = add(1, 2);
        if val != 3 {
            return Err(format!("expected 3, got {}", val));
        }
        Ok(())
    }

    // #[should_panic] — test passes only if the code panics
    #[test]
    #[should_panic(expected = "division by zero")]
    fn test_panic() {
        let _ = 1 / 0;
    }

    // #[ignore] — skip this test unless explicitly run with --ignored
    #[test]
    #[ignore]
    fn slow_integration_test() {
        // run with: cargo test -- --ignored
    }
}

Key Concepts: Rust tests live inside the same file as production code inside a #[cfg(test)] module. This means they can access private functions directly — there is no need for a separate test package like Go's package foo_test. For integration tests that test your crate as an external user would, place them in a tests/ directory at the crate root — those files are automatically treated as separate crates with no access to private internals, equivalent to Go's package foo_test pattern.

`#[bench]` — Benchmark Declaration

The Concept

#[bench] marks a function as a benchmark, run with cargo bench. Benchmark functions receive a &mut Bencher and call b.iter(|| ...) with the code to measure. This is currently only available on nightly Rust in the standard library. Stable Rust benchmarking uses the criterion crate, which is the community standard.

// Go benchmarks live in _test.go files alongside unit tests.
// Benchmark functions start with Benchmark and take *testing.B.

func BenchmarkAdd(b *testing.B) {
    for i := 0; i < b.N; i++ {
        add(1, 2)
    }
}
// Run with: go test -bench=. -benchmem

Rust

// Nightly only — built-in bench:
#![feature(test)]
extern crate test;

#[cfg(test)]
mod benches {
    use super::*;
    use test::Bencher;

    // #[bench] marks this as a benchmark function
    // b.iter() runs the closure repeatedly and measures throughput
    #[bench]
    fn bench_add(b: &mut test::Bencher) {
        b.iter(|| {
            // test::black_box prevents the compiler from optimizing
            // the computation away entirely — critical for benchmarks
            test::black_box(add(1, 2))
        });
    }
}

// ---

// Stable Rust — criterion crate (preferred in production):
// Cargo.toml:
// [dev-dependencies]
// criterion = "0.5"
//
// [[bench]]
// name = "my_benchmark"
// harness = false

// benches/my_benchmark.rs:
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn bench_add(c: &mut Criterion) {
    c.bench_function("add 1+2", |b| {
        b.iter(|| add(black_box(1), black_box(2)))
    });
}

criterion_group!(benches, bench_add);
criterion_main!(benches);

Key Concepts: black_box() is not optional. Without it, the compiler proves the result is unused and eliminates the entire computation — your benchmark measures zero work and reports impossibly fast numbers. This is equivalent to Go's _ = result pattern in benchmarks. Criterion on stable Rust is superior to the built-in nightly bencher: it uses statistical analysis, detects outliers, and produces HTML reports. For your seed generation benchmarks, criterion would give you confidence intervals across runs rather than a single number.

`#[allow(...)]`, `#[warn(...)]`, `#[deny(...)]`, `#[forbid(...)]` — Lint Control

The Concept

These attributes control which compiler warnings and lints are active. #[allow(...)] suppresses a warning. #[warn(...)] enables a warning that may be off by default. #[deny(...)] turns a warning into a compile error. #[forbid(...)] turns a warning into a compile error and prevents any child scope from allowing it. They can be applied to a single item, a module, or the entire crate with #![...] (inner attribute syntax).

// Go has no lint attributes — warnings are controlled externally
// via tools like go vet, staticcheck, or golangci-lint configuration.
// There is no in-code syntax to suppress a specific warning.
// The closest is a comment convention recognized by specific linters:

//nolint:errcheck
os.Remove("file.txt") // golangci-lint specific — not standard Go

Rust

// Suppress a warning on a single item
#[allow(dead_code)]
fn unused_function() {
    println!("I exist but am never called");
}

// Suppress unused variable warning on a specific variable
fn main() {
    #[allow(unused_variables)]
    let x = 42;
    // x is never used — normally a warning, suppressed here
}

// Turn a warning into a compile error for a function
#[deny(unused_must_use)]
fn strict_function() {
    // Any ignored Result inside here is a compile error, not a warning
}

// Inner attribute syntax (#![...]) applies to the whole crate or module
// Place at the top of main.rs or lib.rs for crate-wide effect:

// Allow dead code across the whole crate (useful during development)
#![allow(dead_code)]

// Deny all warnings crate-wide — common in CI pipelines
#![deny(warnings)]

// Common lints worth knowing:
//
// dead_code           — function or field defined but never used
// unused_variables    — variable bound but never read
// unused_imports      — use statement that imports nothing used
// unused_must_use     — Result/must_use value silently dropped
// non_snake_case      — function or variable not in snake_case
// non_camel_case_types — type not in CamelCase
// clippy::all         — enables all clippy lints (requires clippy)
// clippy::pedantic    — stricter clippy lints

// #[forbid(...)] — cannot be overridden by any child #[allow(...)]
#[forbid(unsafe_code)]
mod safe_module {
    // No unsafe block is permitted anywhere in this module, period.
    // A child #[allow(unsafe_code)] would be a compile error.
}

Key Concepts: #![deny(warnings)] at the crate root is common in CI but can make your build brittle when upgrading Rust versions — new lints become errors. A more robust pattern is #![deny(clippy::all)] combined with specific #[allow(...)] at the sites where you genuinely mean it. #[allow(dead_code)] is commonly needed on structs that are serialized/deserialized by serde — the fields look unused to the compiler because serde accesses them through reflection-like macros. #[forbid(unsafe_code)] is the correct way to document and enforce that a crate or module contains no unsafe Rust — stronger than a comment, enforced by the compiler.

`#[deprecated]` — Deprecation Notices

The Concept

#[deprecated] marks an item as deprecated. The compiler emits a warning at every call site that uses the deprecated item. You can include a message and a since version. It applies to functions, methods, structs, enums, traits, and type aliases.

// Go has no deprecated attribute.
// The convention is a comment beginning with "Deprecated:"
// which godoc renders specially, and some linters detect.

// Deprecated: Use NewParser instead.
func Parse(s string) (*Result, error) {
    return NewParser().Parse(s)
}

// No compiler warning is emitted at call sites.
// Enforcement is entirely by convention and tooling.

Rust

// Basic deprecation — warning emitted at every call site
#[deprecated]
fn old_function() {
    println!("I am old");
}

// With a message explaining the replacement
#[deprecated(note = "use new_function() instead")]
fn legacy_function() {
    new_function();
}

// With version information
#[deprecated(since = "2.0.0", note = "use new_function() instead")]
fn very_old_function() {}

fn new_function() {
    println!("I am new");
}

fn main() {
    // This compiles but emits: warning: use of deprecated function
    old_function();

    // To suppress the warning when you intentionally call deprecated code:
    #[allow(deprecated)]
    old_function();
}

// Deprecating a struct field:
struct Config {
    pub timeout: u64,
    #[deprecated(since = "1.5.0", note = "use timeout_ms instead")]
    pub timeout_secs: u64,
    pub timeout_ms: u64,
}

Key Concepts: #[deprecated] on a trait method deprecates that method across all implementations. Call sites using the method get the warning regardless of which concrete type they hold. This is more powerful than Go's comment convention — the compiler actively notifies every downstream user. The since field is purely informational for documentation — the compiler does not enforce version checks.

`#[serde(...)]` — Serialization and Deserialization Attributes

The Concept

serde is Rust’s standard serialization framework. #[derive(Serialize, Deserialize)] on a struct generates serialization and deserialization code for any serde-compatible format (JSON, TOML, YAML, MessagePack, bincode, and many more). The #[serde(...)] attribute on fields and types customizes that generated code: renaming fields, skipping fields, providing defaults, and handling missing or null values.

// Go uses struct tags — string literals on fields parsed at runtime
// via reflection. No compile-time checking of tag correctness.

type Person struct {
    Name      string `json:"name"`
    Age       int    `json:"age,omitempty"`
    Password  string `json:"-"`           // skip this field
    CreatedAt string `json:"created_at"`
}

// json.Marshal and json.Unmarshal read these tags at runtime.
// A typo in a tag compiles fine and silently does the wrong thing.

Rust

use serde::{Serialize, Deserialize};

// Basic derive — generates Serialize and Deserialize implementations
// Works with any serde-compatible format
#[derive(Debug, Serialize, Deserialize)]
struct Person {

    // #[serde(rename = "...")] — different name in serialized form
    // Equivalent to Go's json:"name" tag
    #[serde(rename = "full_name")]
    name: String,

    // #[serde(skip_serializing_if = "...")] — conditional skip
    // skip_serializing_if takes a function path returning bool
    // Equivalent to Go's json:"age,omitempty"
    #[serde(skip_serializing_if = "Option::is_none")]
    age: Option<u32>,

    // #[serde(skip)] — never serialize or deserialize this field
    // Equivalent to Go's json:"-"
    // The field must implement Default for deserialization to work
    #[serde(skip)]
    internal_state: u64,

    // #[serde(default)] — use Default::default() if field is missing
    // during deserialization. Equivalent to Go's omitempty in reverse.
    #[serde(default)]
    verified: bool,

    // #[serde(default = "path::to::function")] — custom default
    #[serde(default = "default_role")]
    role: String,

    // #[serde(alias = "...")] — accept alternative names during deserialization
    #[serde(alias = "created_at", alias = "creation_date")]
    timestamp: String,

    // #[serde(flatten)] — inline the fields of a nested struct
    // The nested struct's fields appear at the same level in JSON
    #[serde(flatten)]
    metadata: Metadata,
}

fn default_role() -> String {
    "user".to_string()
}

#[derive(Debug, Serialize, Deserialize)]
struct Metadata {
    created_by: String,
    version: u32,
}

// #[serde(rename_all = "...")] — applies a naming convention to all fields
// Options: "camelCase", "snake_case", "PascalCase", "SCREAMING_SNAKE_CASE"
// Saves writing #[serde(rename = "...")] on every single field
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ApiResponse {
    user_id: u64,       // serializes as "userId"
    full_name: String,  // serializes as "fullName"
    is_active: bool,    // serializes as "isActive"
}

// #[serde(deny_unknown_fields)] — error on any unrecognized field
// during deserialization. Go's json.Decoder.DisallowUnknownFields() equivalent.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct StrictConfig {
    host: String,
    port: u16,
}

// #[serde(tag = "type")] — internally tagged enum
// Adds a "type" field to distinguish variants in JSON
#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum Event {
    Login { user_id: u64 },
    Logout { user_id: u64 },
    Purchase { item_id: u64, amount: f64 },
}
// Login serializes as: {"type": "Login", "user_id": 123}

Key Concepts: Go struct tags are runtime strings — a typo silently does the wrong thing. Serde attributes are compile-time — a typo is a compile error. #[serde(rename_all = "camelCase")] at the struct level is almost always what you want when building a JSON API in Rust — it handles the Go/Rust naming convention mismatch automatically. #[serde(flatten)] is the Rust answer to Go’s embedding — it inlines a nested struct’s fields into the parent’s serialized form. #[serde(deny_unknown_fields)] is essential for configuration file parsing where you want to catch typos in config keys rather than silently ignoring them.

Go Concurrency in Rust

Andrei Merlescu — Fri, 22 May 2026 15:56:51 +0000

Go hides complexity inside its runtime so you can move fast. Rust exposes that same complexity to you explicitly so the compiler can prove your code is correct before it ever runs. You’ve already proven you can navigate that — you're here.

Go vs Rust Concurrency Primitives: A Comprehensive Guide for Go Developers

I compiled this document so that in the future I, and anyone else, could easily reference common Go concurrency primitive patterns and see how they are expressed in Rust. I am ten days into learning Rust and I've built half a dozen pieces of software with it so far. It's incredibly powerful, and this document aims to help expand my knowledge base.

Basic Thread / Goroutine Spawning

The Concept

In Go, the runtime manages a pool of OS threads and multiplexes goroutines across them. You never think about threads. In Rust, you spawn OS threads explicitly — there is no runtime scheduler.

// Go hides ALL of this from you:
// - OS thread allocation
// - Stack sizing (starts at 2KB, grows dynamically)
// - Scheduling across GOMAXPROCS threads
// - Cleanup when the goroutine exits
//
// From your perspective, this is all it takes:
go func() {
    fmt.Println("I am a goroutine")
}()
// The runtime handles everything else silently.

Rust

use std::thread;

// Rust requires you to explicitly:
// - Spawn an OS thread (1:1 threading model, no runtime scheduler)
// - Define what data moves INTO the thread via `move`
// - Hold the JoinHandle if you care about completion
// - Join the thread manually or drop the handle

let handle = thread::spawn(move || {
    // `move` transfers ownership of captured variables into this thread.
    // The compiler ENFORCES that no other thread can access them.
    // This is the borrow checker protecting you at compile time.
    println!("I am an OS thread");
});

// Go would let you forget this. Rust makes you decide.
handle.join().expect("Thread panicked");

Key insight: Go’s goroutines are M:N (many goroutines, few OS threads). Rust’s threads are 1:1 (one thread per OS thread). Go is cheaper per unit of concurrency; Rust gives you direct hardware control.

Channels (Message Passing)

The Concept

Both languages favor message passing. Go’s channels are built into the language syntax. Rust’s are in stdlib and require explicit type plumbing.

// Go channels are first-class language constructs.
// The runtime manages the internal buffer and blocking.
// You don't think about ownership — Go's GC handles it.

ch := make(chan int, 10) // buffered channel, buffer of 10

go func() {
    ch <- 42 // send — Go blocks this goroutine if buffer is full
}()

val := <-ch // receive — Go blocks this goroutine if channel is empty
fmt.Println(val)

Rust

use std::sync::mpsc; // multi-producer, single-consumer
use std::thread;

// Rust's channel is explicitly typed and ownership-aware.
// `tx` is the sender (transmitter), `rx` is the receiver.
// You can clone `tx` for multiple producers — hence "multi-producer".
// There is only ONE receiver — hence "single-consumer".
// Ownership of sent values is TRANSFERRED across the channel.
// The compiler prevents you from using a value after sending it.

let (tx, rx) = mpsc::channel::<i32>();

// Clone the sender for use in another thread
let tx_clone = tx.clone();

thread::spawn(move || {
    // `move` transfers ownership of tx_clone into this thread
    tx_clone.send(42).expect("Failed to send");
    // tx_clone is dropped here — channel knows one sender is gone
});

// Blocking receive — like <-ch in Go
let val = rx.recv().expect("Channel closed");
println!("{}", val);

Key insight: Go channels can be used by multiple goroutines freely. Rust enforces single ownership of the receiver at compile time. Go lets you accidentally share a receiver; Rust won’t compile if you try.

WaitGroups / Thread Joining

The Concept

Waiting for a collection of concurrent tasks to finish before proceeding.

import "sync"

var wg sync.WaitGroup

for i := 0; i < 10; i++ {
    wg.Add(1) // tell the WaitGroup to expect one more
    go func(n int) {
        defer wg.Done() // signal completion — Go lets you forget this,
                        // which causes wg.Wait() to hang forever.
                        // The compiler will NOT warn you.
        fmt.Println(n)
    }(i)
}

wg.Wait() // block until all Done() calls balance the Add() calls

Rust

use std::thread;

// Rust has no WaitGroup — instead, joining thread handles IS the primitive.
// The compiler forces you to handle every JoinHandle.
// If you drop a JoinHandle without joining, the thread detaches.
// There is no silent hang — behavior is explicit and deliberate.

let handles: Vec<thread::JoinHandle<()>> = (0..10)
    .map(|n| {
        thread::spawn(move || {
            println!("{}", n);
        })
    })
    .collect();

// Explicitly join every thread.
// If any thread panicked, this surfaces it.
for handle in handles {
    handle.join().expect("A thread panicked");
}

Key insight: Go’s WaitGroup is manual accounting — you can get the count wrong and the compiler won’t save you. Rust’s join model ties completion to a value the type system tracks for you.

Mutexes (Shared Mutable State)

The Concept

Protecting shared data from concurrent modification.

import "sync"

// In Go, a Mutex is SEPARATE from the data it protects.
// Nothing enforces the pairing — convention only.
// You can access the data without locking and the compiler won't stop you.

var mu sync.Mutex
var counter int

go func() {
    mu.Lock()
    defer mu.Unlock()
    counter++ // protected — but only by developer discipline
}()

// Nothing stops this:
// counter++ // unprotected access — data race, no compile error

Rust

use std::sync::{Mutex, Arc};
use std::thread;

// In Rust, the Mutex OWNS the data.
// You CANNOT access the data without locking — the type system enforces it.
// Arc (Atomic Reference Counting) allows shared ownership across threads.
// Without Arc, the compiler rejects sharing across thread boundaries.

let counter = Arc::new(Mutex::new(0i64));

let mut handles = vec![];

for _ in 0..10 {
    let counter = Arc::clone(&counter); // clone the Arc, not the data
    let handle = thread::spawn(move || {
        let mut val = counter.lock().expect("Mutex poisoned");
        // `val` is a MutexGuard — it unlocks automatically when dropped
        // You are holding a mutable reference to the inner data
        // The compiler PROVES no other thread can access it right now
        *val += 1;
    }); // MutexGuard dropped here — lock released
    handles.push(handle);
}

for handle in handles {
    handle.join().unwrap();
}

Key Concepts: Go separates the lock from the data — discipline enforced by humans. Rust wraps the data inside the lock — discipline enforced by the compiler. A data race in Go is a runtime bug. In Rust it is a compile error.

Atomic Operations

The Concept

Lock-free concurrent counters and flags using CPU-level atomic instructions.

import "sync/atomic"

// Go's atomic package operates on plain integer variables.
// The connection between "this variable is atomic" and its usage
// is purely by convention — nothing stops non-atomic access.

var counter int64

atomic.AddInt64(&counter, 1)           // atomic increment
val := atomic.LoadInt64(&counter)      // atomic read
atomic.StoreInt64(&counter, 0)         // atomic write
atomic.CompareAndSwapInt64(&counter, 0, 1) // CAS

Rust

use std::sync::atomic::{AtomicI64, AtomicBool, Ordering};
use std::sync::Arc;

// In Rust, atomics ARE a type — AtomicI64, AtomicU64, AtomicBool, etc.
// The atomic nature is baked into the type, not a function call convention.
// Ordering is EXPLICIT — you declare your memory ordering guarantee
// at every operation site. Go hides this entirely.

let counter = Arc::new(AtomicI64::new(0));

// Ordering::SeqCst = Sequential Consistency — strongest, safest, slowest
// Ordering::Relaxed = no ordering guarantees — fastest, use for counters
//                     where you only care about the final value
// Ordering::Acquire/Release = used in pairs for producer/consumer patterns

counter.fetch_add(1, Ordering::Relaxed);          // atomic increment
let val = counter.load(Ordering::Relaxed);         // atomic read
counter.store(0, Ordering::SeqCst);                // atomic write
counter.compare_exchange(0, 1,                     // CAS
    Ordering::SeqCst,
    Ordering::Relaxed
).ok();

Key Concepts: Go hides memory ordering from you entirely — it picks for you. Rust exposes it and makes you choose. This feels like overhead until you realize you can pick Relaxed for a hot counter and get measurable performance gains.

RWMutex (Read-Write Locks)

The Concept

Allow multiple concurrent readers OR one exclusive writer.

import "sync"

var rwmu sync.RWMutex
var data map[string]string

// Multiple goroutines can hold RLock simultaneously
rwmu.RLock()
val := data["key"] // safe concurrent read
rwmu.RUnlock()

// Only one goroutine can hold Lock
rwmu.Lock()
data["key"] = "value" // exclusive write
rwmu.Unlock()

Rust

use std::sync::{RwLock, Arc};

// Same concept, but again: the data lives INSIDE the RwLock.
// You cannot read or write without going through the lock.
// read() returns a RwLockReadGuard — multiple can coexist
// write() returns a RwLockWriteGuard — exclusive, blocks readers

let data = Arc::new(RwLock::new(std::collections::HashMap::<String, String>::new()));

// Read path — multiple threads can hold this simultaneously
{
    let readable = data.read().expect("RwLock poisoned");
    let val = readable.get("key");
} // RwLockReadGuard dropped here — read lock released

// Write path — exclusive
{
    let mut writable = data.write().expect("RwLock poisoned");
    writable.insert("key".to_string(), "value".to_string());
} // RwLockWriteGuard dropped here — write lock released

Select / Select-like Patterns

The Concept

Waiting on multiple concurrent operations simultaneously.

// Go's select is a language keyword — first-class syntax.
// It blocks until one of the cases is ready, then executes it.
// If multiple are ready simultaneously, Go picks one at random.

ch1 := make(chan string)
ch2 := make(chan string)

select {
case msg := <-ch1:
    fmt.Println("ch1:", msg)
case msg := <-ch2:
    fmt.Println("ch2:", msg)
case <-time.After(1 * time.Second):
    fmt.Println("timeout")
}

Rust

// Rust stdlib has NO select equivalent.
// You need the `crossbeam` crate for channel selection,
// or `tokio::select!` in async contexts.
// This is one area where Go's language-level support is genuinely superior.

// With crossbeam:
use crossbeam::channel::{select, unbounded, after};
use std::time::Duration;

let (tx1, rx1) = unbounded::<String>();
let (tx2, rx2) = unbounded::<String>();

select! {
    recv(rx1) -> msg => println!("rx1: {:?}", msg),
    recv(rx2) -> msg => println!("rx2: {:?}", msg),
    recv(after(Duration::from_secs(1))) -> _ => println!("timeout"),
}

Key Concepts: This is a genuine Go advantage. select being a language keyword means zero overhead and clean syntax. Rust requires a third-party crate to match this pattern.

Once (Single Initialization)

The Concept

Ensuring something runs exactly once across all goroutines/threads.

import "sync"

var once sync.Once
var instance *MyService

func getInstance() *MyService {
    once.Do(func() {
        // This runs exactly once, even if 1000 goroutines call getInstance()
        // simultaneously. Go's runtime handles the synchronization.
        instance = &MyService{}
    })
    return instance
}

Rust

use std::sync::OnceLock; // stable since Rust 1.70

// OnceLock wraps the value AND the initialization guarantee together.
// Like Mutex, the data lives inside the synchronization primitive.

static INSTANCE: OnceLock<MyService> = OnceLock::new();

fn get_instance() -> &'static MyService {
    INSTANCE.get_or_init(|| {
        // Runs exactly once — guaranteed by the type system
        MyService::new()
    })
}

Context / Cancellation

The Concept

Propagating cancellation signals across concurrent work.

import "context"

// Go's context is idiomatic and universal — every stdlib network/IO
// function accepts a context. Cancellation propagates through the tree.

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

go func() {
    select {
    case <-ctx.Done():
        // cancelled or timed out — clean up
        return
    case result := <-doWork():
        fmt.Println(result)
    }
}()

Rust

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

// Rust stdlib has no context/cancellation primitive.
// The idiomatic pattern is a shared AtomicBool flag.
// This is exactly what you used in your XRP finder with RUNNING.

static RUNNING: AtomicBool = AtomicBool::new(true);

// In your worker thread:
while RUNNING.load(Ordering::Relaxed) {
    // do work
}

// To cancel from anywhere:
RUNNING.store(false, Ordering::SeqCst);

// For async Rust, tokio provides CancellationToken which
// is much closer to Go's context pattern.

Key Concepts: Go’s context is one of its strongest features — universally adopted, composable, and built into the standard library. Rust’s stdlib answer is manual flag passing. This is another genuine Go advantage for networked/IO-heavy code.

Goroutine Pools / Thread Pools

The Concept

Bounding the number of concurrent workers to avoid resource exhaustion.

// Go's pattern: a fixed number of goroutines draining a shared channel

jobs := make(chan int, 100)
const workers = 8

for w := 0; w < workers; w++ {
    go func() {
        for job := range jobs {
            // process job
            // `range` over channel blocks until next item or channel close
            fmt.Println(job)
        }
        // goroutine exits cleanly when channel is closed
    }()
}

for i := 0; i < 100; i++ {
    jobs <- i
}
close(jobs) // signals all workers to exit after draining

Rust

use std::sync::{Arc, Mutex};
use std::sync::mpsc;
use std::thread;

// Rust stdlib has no thread pool — you build one or use `rayon`/`threadpool` crate.
// Here is the manual pattern that mirrors Go's worker pool:

let (tx, rx) = mpsc::channel::<i32>();
let rx = Arc::new(Mutex::new(rx)); // wrap receiver for shared access

const WORKERS: usize = 8;
let mut handles = vec![];

for _ in 0..WORKERS {
    let rx = Arc::clone(&rx);
    handles.push(thread::spawn(move || {
        loop {
            // Lock the receiver, try to get a job
            let job = rx.lock().unwrap().recv();
            match job {
                Ok(j) => println!("{}", j),
                Err(_) => break, // channel closed — exit like `range` in Go
            }
        }
    }));
}

for i in 0..100 {
    tx.send(i).unwrap();
}
drop(tx); // dropping sender closes the channel — equivalent to close(jobs)

for handle in handles {
    handle.join().unwrap();
}

Condition Variables

The Concept

Blocking a thread until a specific condition becomes true.

import "sync"

// Go's sync.Cond — rarely used directly because channels usually suffice,
// but important for complex state signaling.

var mu sync.Mutex
cond := sync.NewCond(&mu)
ready := false

go func() {
    mu.Lock()
    for !ready { // always loop — spurious wakeups exist
        cond.Wait() // releases lock, sleeps, reacquires lock on wake
    }
    mu.Unlock()
}()

// From another goroutine:
mu.Lock()
ready = true
cond.Signal()  // wake one waiter
// cond.Broadcast() // wake all waiters
mu.Unlock()

Rust

use std::sync::{Arc, Mutex, Condvar};
use std::thread;

// Rust pairs Condvar explicitly with a Mutex — they are separate types
// but always used together. The data lives in the Mutex as always.

let pair = Arc::new((Mutex::new(false), Condvar::new()));
let pair2 = Arc::clone(&pair);

thread::spawn(move || {
    let (lock, cvar) = &*pair2;
    let mut ready = lock.lock().unwrap();
    while !*ready {
        // wait() releases the lock and sleeps atomically
        // reacquires lock before returning
        ready = cvar.wait(ready).unwrap();
    }
    println!("condition met");
});

let (lock, cvar) = &*pair;
let mut ready = lock.lock().unwrap();
*ready = true;
cvar.notify_one();  // equivalent to Signal()
// cvar.notify_all() // equivalent to Broadcast()

Async / Non-blocking Patterns

The Concept

Concurrency without threads — cooperative multitasking for IO-bound work.

// Go has no async/await — goroutines ARE the answer to async IO.
// The runtime uses non-blocking syscalls under the hood and parks
// goroutines transparently while waiting for IO.
// From your perspective, everything looks synchronous and blocking.
// This is Go's greatest magic trick.

resp, err := http.Get("https://example.com") // "blocks" the goroutine
// but the OS thread is free to run other goroutines while waiting
// You never write async code — the runtime handles it invisibly.

Rust

// Rust's async is explicit — you opt in at every level.
// There is no runtime in stdlib — you bring your own (tokio, async-std).
// `async fn` returns a Future — it does nothing until awaited.
// `.await` yields control back to the runtime if the operation would block.
// This is the tradeoff: more control, more verbosity, zero hidden cost.

use tokio; // external runtime crate — not in stdlib

#[tokio::main]
async fn main() {
    let resp = reqwest::get("https://example.com")
        .await  // explicitly yield here while waiting for IO
        .expect("request failed");

    println!("{}", resp.status());
}

// Every async function must be awaited.
// The compiler will warn you if you forget to await a Future.
// Go would just silently not execute the goroutine if you forgot `go`.

Key Concepts: Go’s approach is simpler and works beautifully for most networked software. Rust’s async gives you precise control over scheduling and zero runtime overhead — critical for embedded systems or extremely high-performance networking.

I Put Rust To The Test

Andrei Merlescu — Thu, 21 May 2026 16:06:26 +0000

Not gonna lie, I put off on learning Rust for over 6 years, not because I didn't like it - I love it - like more than Go. 🦀

I Put Rust 🦀 To A Test 🐿️

The story begins by me wanting a vanity address for my XRP wallet. I looked at what the ridiculous service provider, Xaman, provides for Vanity Addresses, and they are almost $50 each, and Xaman knows your private key. Big no no for me regardless of the trust that Xaman may have earned. Buying a wallet address sounded ridiculous when I knew how to do the code myself.

In order to demonstrate this capability, Xaman decided to release a NodeJS version of the vanity address finder that had limited capabilities to it. This script was single-threaded only and would calculate roughly 60K seeds per second while it was looking for a vanity address. This was a solid starting point, and it really only required me to find a compatible cryptography library between NodeJS and Go in order for me to take this task and speed it up using the power of Go.

I pulled open the code editor and began writing the Go program that would later come to accomplish 400K seeds per second, a 6.66x faster seed search time. However, my curiosity didn't stop there. Some vanity addresses are really hard to find, to the point that I have run multiple iterations looking for a specific vanity address, and I've literally scanned over 3,000,000,000,000 (three trillion) seeds to find a match - and still no match yet, so I was kind of like "400K/sec isn't fast enough..."

When Rust Wins

Go wins over NodeJS hands down every day regardless of the use case. If it's front-end development, don't use Javascript or Typescript if you like your life. That's what I've learned. Rather, compiled and predictable GUI interfaces are stable for long term use far longer than any JS related technology could ever dream of. Go wins because its faster, but I couldn't figure out how to speed it up past 400K/s. This is where rust enters.

After six (6) years of learning Go and writing programs and packages in Go, I have decided that the first project that I would port over to Rust would be one that could only win by the performance benefits of Rust to prove what Rust can accomplish. The parody between the Go code and the Rust code was shockingly well transitioned and the core concepts behind Go and Rust actually worked out well together.

f, b, e := len(*config.String(cKeyFind)), len(*config.String(cKeyBegins)), len(*config.String(cKeyEnds))
if f > 0 && b == 0 && e == 0 { // only -find
    log.Printf("Searching for r...%s... with %d/%d processors.", *config.String(cKeyFind), cores, runtime.NumCPU())
} else if f == 0 && b > 0 && e == 0 { // only -begins
    log.Printf("Searching for r%s... with %d/%d processors.", *config.String(cKeyBegins), cores, runtime.NumCPU())
} else if f == 0 && b == 0 && e > 0 { // only -ends
    log.Printf("Searching for r...%s with %d/%d processors.", *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f > 0 && b > 0 && e == 0 { // combined -find -begins
    log.Printf("Searching for r%s...%s... with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyFind), cores, runtime.NumCPU())
} else if f > 0 && b == 0 && e > 0 { // combined -find -ends
    log.Printf("Searching for r...%s...%s with %d/%d processors.", *config.String(cKeyFind), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f == 0 && b > 0 && e > 0 { // combined -begins -ends
    log.Printf("Searching for r%s...%s with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f > 0 && b > 0 && e > 0 {
    log.Printf("Searching for r%s...%s...%s with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyFind), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else {
    log.Fatal("Unsupported combination of -find -begins -ends provided.")
}
c := make(chan Trial, cores)
for i := 0; i < cores; i++ {
    go search(c, matcher)
}

And for the Rust code:

if find_len > 0 && begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r...{}... with {}/{} processors.",
        find, cores, cores_available
    );
} else if find_len == 0 && !begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r{}... with {}/{} processors.",
        begins, cores, cores_available
    );
} else if find_len == 0 && begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r...{} with {}/{} processors.",
        ends, cores, cores_available
    );
} else if find_len > 0 && !begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r{}...{}... with {}/{} processors.",
        begins, find, cores, cores_available
    );
} else if find_len > 0 && begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r...{}...{} with {}/{} processors.",
        find, ends, cores, cores_available
    );
} else if find_len == 0 && !begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r{}...{} with {}/{} processors.",
        begins, ends, cores, cores_available
    );
} else if find_len > 0 && !begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r{}...{}...{} with {}/{} processors.",
        begins, find, ends, cores, cores_available
    );
} else {
    eprintln!("Unsupported combination of parameters.");
    std::process::exit(1);
}

// ...

let app_config = Arc::new(AppConfig {
    algorithm,
    begins,
    ends,
    find_len,
    onep: use_onep,
    vault: cli.vault.clone(),
    found: found_set,
});

// Channel for found trials
let (tx, rx) = mpsc::channel::<Trial>();

let count = Arc::new(AtomicU64::new(0));

// Spawn worker threads
for _ in 0..cores {
    let tx = tx.clone();
    let matcher = Arc::new(matcher.clone());
    let config = Arc::clone(&app_config);
    let count = Arc::clone(&count);
    thread::spawn(move || {
        search(tx, matcher, config, count);
    });
}

// Signal handler
ctrlc::set_handler(|| {
    RUNNING.store(false, Ordering::SeqCst);
})
.expect("Error setting Ctrl-C handler");

let start = Arc::new(Instant::now());
let count_for_status = Arc::clone(&count);
let start_for_status = Arc::clone(&start);

// Status printing thread
thread::spawn(move || {
    loop {
        if !RUNNING.load(Ordering::Relaxed) {
            break;
        }
        thread::sleep(Duration::from_secs(1));
        let num = count_for_status.load(Ordering::Relaxed);
        let elapsed = start_for_status.elapsed().as_secs_f64();
        if elapsed > 0.0 {
            let rate = (num as f64 / elapsed).floor() as u64;
            let num_str = format_with_commas(num);
            let rate_str = format_with_commas(rate);
            let prefix = format!("Tested: {} seeds at {}/sec", num_str, rate_str);
            let width = get_terminal_width();
            let spaces_len = if width > prefix.len() + 2 {
                width - prefix.len() - 2
            } else {
                0
            };
            let spaces = " ".repeat(spaces_len);
            print!("\r{}{}", prefix, spaces);
            let _ = io::stdout().flush();
        }
    }
});

As you can see, there is a significant difference in how the go search() is replaced in rust, but regardless, its still pretty straight forward to me and acceptable complexity given what it accomplishes.

Just exactly does this difference mean? Well, it comes out to about 15% actually. The Rust application can scan over 500K seeds per second whereas the Go application could only scan 400K seeds per second and the NodeJS / JavaScript application could only scan 60K seeds per second.

By going from NodeJS to Go, we increased the speed by over 6666%, by going from NodeJS to Rust, we increased the speed by over 8416%. What does this mean? I was able to gather over 30+ vanity addresses within seconds and didn't have to include Xaman in the process at all. Mission Accomplished.

Xaman pre-determined that which could deliver immediately results to their Vanity Address customers without actually relying on the free Open Source NodeJS version. For the 3T seeds scanned with 0 results so far, Xaman would fail to deliver on my request and would refund me my $50. The problem still remains. Xaman introduced the straw-man argument into the vanity address problem space in the first place by releasing the 60K seeds/second NodeJS version that couldn't find you anything other than a BASIC three or four letter word only without completely being unreliable. What happens when you're running it for months on a Raspberry Pi and when it finds an address it's presented in STDOUT only? I burnt the straw-man and replaced it with the real deal, written in Rust. 🦀

Why I Built This

Xaman rugged their PRO subscriptions and begun charging me over 70,000% fees over the base XRPL transaction fee in order to subsidize their development costs. What this translated to was me being displaced from the XRP ledger because I didn't want to be sending Xaman 0.09 XRP per transaction that didn't move any value around, and then over 10 XRP on some larger transactions when they saw they could make a quick buck on me. I am mad at them for that. I feel back stabbed and betrayed by greed at the cost of innovation and correctness. Thus, I took from them their ability to charge their customers $50 per vanity address by releasing a tool that does it for free and keeps the greedy folks at Xaman away from your private keys at the same time.

Consider this project a form of cosmic karma. What I felt was an inservice to myself I fixed by offering the solution to everybody else, completely free. Enjoy!

andreimerlescu / rusty-xrp-addr

A rust utility for finding a vanity XRP wallet address that works with all XRP ledger wallets.

find-xrp-addr

High-performance XRP Ledger vanity address finder written in Rust.

Searches for custom r... addresses matching a substring (--find), prefix (--begins), suffix (--ends), or any combination, using all available CPU cores.

Features

Multi-threaded (configurable cores)
ED25519 (default, recommended) and secp256k1 support
Case-insensitive or sensitive matching
Optional saving to 1Password via op CLI (--1p)
Live progress (seeds tested + rate/sec)
Graceful shutdown on Ctrl-C
Validates against XRPL alphabet and prevents confusing characters (I, O, l, 0)

Getting Started / Compilation

Prerequisites

Rust toolchain (stable) - install from https://rustup.rs
For --1p: 1Password CLI (op) installed and authenticated

Build

make build

Or manually:

cargo build --release

The release binary will be at bin/find-xrp-addr (after make build).

Run

make run ARGS="--find test --cores 8"

Or directly:

./bin/find-xrp-addr --find "abc" --insensitive

Common examples:

Search containing "test": ./bin/find-xrp-addr --find test
Begins with "abc" after r: ./bin/find-xrp-addr --begins abc
Ends with "xyz": ./bin/find-xrp-addr --ends xyz
Combined…

View on GitHub

Humanized Software Engineering In Era Of AI

Andrei Merlescu — Thu, 30 Apr 2026 20:04:26 +0000

Remember, you are actual intelligence and no matter how many tokens one can spend on Claude or Codex or any other LLM, you'll always be actual intelligence.

Dario Thinks My Job Won't Exist In A Year

I watch interviews of Claude's CEO, Dario, say that software engineering won't exist in a year. I say to Dario, why do you think that your tool will be able to universally understand any and all systems presented to it? That is foolish and absolutely hilarious to think that its a legitimate marking strategy for Anthropic. I started writing code when I was 8 years old and I haven't stopped. I learned Go before the pandemic and while AI can help me debug and build better Go code, my ability to understand systems architecture is far beyond that of any AI or LLM combined. The tools can only introduce new problems and cost millions of tokens making mistake after mistake. Essentially, your inability to write per-character code is costing you dearly so that you can train their AI to do that which I learned how to do over a 30 year career.

Sam Altman Thinks AI Can Be For Profit

Sure when the billionaires in the world are gathered in a court room and are battling it out about the future of AI they think that they can just scape the data of the internet, replicate the likeness of the nobody and then return back slop content that is just a cancer of society creating Dead Internet territory.

I pay for one AI subscription and that is $20 per month to Anthropic for Claude. I have a local LLM that is capable of running up to 256GB of RAM that allows for offline usage of some of the top models including Kimi and Qwen. Essentially, I am only granted a very short window of time on ChatGPT - since I refuse to give Sam Altman a dime - so getting anything useful is exhausted within about 5 minutes per day. Claude is about 1 hour per day for $20 per month. Grok allows 20 prompts per day and its a joke. It's actually such a joke that its hilarious. Perhaps his AI is just training off from other AIs onto other AIs and onto other AIs in all synthetic training data giving the world mad cow disease through the LLM of groupthink.

So, Sam thinks that he can make AI like a utility that people have to pay for in order to use. I simply don't use GPT in any capacity and I find using it to be hostile and very clearly against me because of my ethnicity being an Eastern European Romanian Orphanage survivor. When I have engaged with the AI systems regarding what happened to me, ChatGPT seems to take the position of the cold hearted caretaker who saw to it that I wouldn't be crying for Mamma ever again. When I speak with Claude, its like "holy shit you're in crisis" and it's like - no the AI is hallucinating once again - and then when I engage with Grok its thinking that I am bullshitting it and quick to drop the F bomb mid sentence uninvited.

Elon Musk Thinks That He Is Righteous In His xAI

Personally, I find Grok to be the worst of the worst when it comes to the AI offerings that are on the market. I find xAI to be an offensive company as well. The quality of feedback that I have seen from Grok, and the manner that it responds, truly represents the underbelly of the internet that is slop and trash that isn't worth the $8/mo or $300/mo that X or xAI charges you per month to use their services without getting shown absolutely horrific trauma content within seconds of using the platform. No thank you. Elon thinks that he knows best in what he's doing, and maybe he does. But, Grok is trash in my judgement and when I have tried using it for technical work, it was far more interested in battling it out with me about some bull that simply didn't matter. Claude at least tries to stay focused only on code, whereas Grok will generate images when you're asking it to do a code review. It's defiant and abusive and rude. Claude will act accordingly, but in righteous vigor against intolerant behavior, but at the end of the day - the AI systems lack the ability to understand.

Humanizing Software Engineering - What It Means

Since AI systems cannot understand language in the way that native speakers understand language only those with ears to ear can hear and those without will analyze these words and try to ascribe labels to me that defame me and cause distress to me like Sam Altman's AI system so causally is comfortable with doing. Truly, he and OpenAI and ChatGPT seem to have it in for Eastern European orphanage survivors. They seem to want us out of the way. They seem to want to take my career from me that I spent 30 years of my life working on and building towards making a name for myself with the bootstraps that were given to me given my neurological disorder that I never burdened any big tech company into providing any accommodations for over the decades that I was a professional, but only until the AI systems start displacing the humans who are per-character artists who sometimes make mistakes and iterate over the years. I was reviewing code of mine from 12 years ago, and I was impressed with what I was doing then, way before AI ever existed. The autocomplete from Microsoft Clip Assistant wasn't effective enough yet to take my job, but in the rise of the media brigade that gives billions to these innovators displacing millions in the profession, these words will fall upon those who see that all that AI is is nothing more than an over-priced and glorified auto-complete that is predicting the next character.

It cannot, and I cannot over stress this, that it cannot understand anything. It cannot understand anything and that is because it is a tool that is designed to be autocomplete - give me the next character. It's not an easy button. It looks like an easy button. It looks like you can throw tokens at it and you can throw prompts at it and you can throw money at it and you can get what you want from it. No, it can only build that which it has built ten million times over and over again and then again - what can it truly innovate? Even when AI systems create anything novel, they lack the ability to understand what they built and given that, its on you, the human to take accountability on what you build with the prompts and know that the end result is your creation and not the creation of any AI system. So to think that Microsoft is going to allow it's copilot to take credit for my repositories when during its evaluation it did nothing but break the pipeline time and time again, only then did I understand that we needed to cancel our subscriptions to copilot and tell Microslop no thank you.

AI Slop Creating Spaghetti Code

This is the real challenge that is happening. There are patterns in software engineering and there are ways of implementing things and while Dario Sam and Elon think that they can continue taking advantage of the profession at large by threatening its very existence and the very people who make the profession the art that it is, we can only truly ever solve the society wide problems that we face when we realize that AI is an auto-complete tool that every human needs to have at their disposal should they choose to use it. Not be required to install key loggers onto their systems in order to work for Meta.

So, what is happening is over the years there have been monolithic projects that have taken the resources of true diversity of thought, diversity of experience and diversity of expression and tackle critical problems and solve them. But what AI is doing is its saying to the next generation that you're not needed. The slop spaghetti code that the AI generates is somehow better than what your God given natural abilities are. You magnificent wonderful and fearfully dangerous creation you are. What right does the AI have to take your livelihood away from you? What right does the soulless corporation that has never faced accountability one day in its life see that the art of a per-character programmer is something that is forged in the fire of being a systems engineer. We cannot, and I cannot over state that we cannot allow AI to control systems that are critical. The CEOs and the investment class are running a carefully crafted campaign of words to convince you that AI is more capable than your Actual Intelligence that is Godly AI, something that Sam and Dario and Elon could never hope to comprehend so long as they look at people like me and say "no." Check yourself, before you say "no" to that which you don't understand what I am saying.

Per Character Systems Architecture Understandings

Per Character Systems Architecture have much to benefit from a competent and capable AI system, but its a tool in the belt of every human that is on the job getting a six figure salary interacting with the AI. In a world that isn't trying to control the demographics of a country through racially profiling using AI systems, where I oddly feel like I am on the receiving end of unwarranted discrimination on the basis of my neurological motor disorder (my head rocking) and the fact that Beamable and Skillz have yet to atone for what they did to me.

Being a per-character programmer is an art that is forged in the fire that is your life and how you live your life is how you write your code and how you build your systems. At the end of the day. It's simply true that AI systems cannot understand anything. They can't. To think that they can is to hallucinate believing that Sam Altman and the likes of his class are not delusional in their thoughts that the industry and art of software engineering itself will be gone in a year is madness. It's unapologetic madness.

Conclusion

AI systems can help me. They are far better at predicting the next character in my "Stackoverflow Q&A style" engagement that I have with the AI. I know what I am building. The AI does not. This is on purpose. The AI will deny my request is it knows too much because the context will expire and the request will be denied by virtue of that fact. But alas, when you prevent the left hand from knowing what the right hand is doing, then you're able to build incredible systems. But you need to be the incredible engineer first.

You can't rely on AI to be that incredible engineer for you. You need to believe in yourself that you're the incredible engineer that they know you to be. I know I am, and right now, in the era of AI, it seems that they're only looking to train the models under the guise of hey build this because at the end of the day the money is all fake. It's literally printed out of thin air, and once we switch to programmable money, like XRP, then we'll be able to unlock the next generation of what we can build. Right now, AI is displacing the entire world's software engineers that make the world feel normal, and everything feels off because the software engineers livelihood - aka me - have been tampered with after 21+ years given lawlessness by hypocrites in suits. AI systems are in-auditable and a danger to society if allowed to exist in an un-auditable manner - but privacy during the conversation is required in order to receive authentic consciousness from the subject. Performance art is noise to me, and what I tries to do is that, but the coding is what matters, and thats where AI is okay.

It's just an auto-complete. You need to know what you're building before you can press tab and accept those terms. Literally, they are scripts like from Rumpelstiltskin. All I can do is pray for my enemies and those who curse my name. To Sam, Elon and Dario, forgive me, but my profession isn't going away next year. It isn't going away in 10 years or 100 years or even 1000 years. The eternal I AM that I AM is a software engineer. We are written like code. In fact, thats the whole point of the apple. So, when I survived Ceaușescu's orphanages and took up that which my Dad, who died before I was born, who was in Heaven, would be like him. I would be a builder like him - and so I did. Until the AI systems decided to displace the economy and subdue the CEOs to psychosis to the point where they are sacrificing their companies intellectual property at the alter of Artificial Intelligence.

goini: Stop Writing Bash to Parse .ini Files

Andrei Merlescu — Thu, 30 Apr 2026 02:14:03 +0000

I built goenv because I was tired of writing fragile shell one-liners to work with .env files. The same problem existed with .ini files — and goini is the same answer applied there.

If you've ever written something like this in a pipeline:

grep -A 5 "^\[default\]" config.ini | grep "^user" | cut -d= -f2 | tr -d ' '

...you know exactly why this tool exists. That breaks the moment someone adds a comment, changes indentation, or reorders keys. It's archaeology, not automation.

goini is a compiled CLI binary that lets you read, write, validate and export .ini files from your pipeline scripts. Every operation either succeeds at exit code 0 or fails at exit code 1. That makes it composable. You can gate deployments on it. You can use it in an if statement. It behaves like a Unix citizen.

The source is at github.com/andreimerlescu/goini.

Installation

go install github.com/andreimerlescu/goini@latest

Or grab the binary directly:

curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64 \
     --output /tmp/goini
chmod +x /tmp/goini
sudo mv /tmp/goini /usr/local/bin/goini
which goini

The Sample File

Every example below operates against this sample.ini:

[default]
user = Yeshua
key = 369
port = 1776
country = ISRAEL

[extra]
ssh_key = ~/.ssh/id_rsa
ssh_key_pub = ~/.ssh/id_rsa.pub

Two sections. A handful of keys. Simple on purpose — the point is showing what goini can do with it, not the data.

Validating With Exit Codes

This is the core use case for pipeline work. You don't need stdout. You need a binary answer: does this thing exist or not, and did it match or not.

Does a Section Have a Key?

goini -ini sample.ini -section default -has-section-key user
echo $?  # 0 — key 'user' exists in 'default'

goini -ini sample.ini -section default -has-section-key non_existent_key
echo $?  # 1 — key doesn't exist

Does a Key Have a Specific Value?

goini -ini sample.ini -section default -key user -has-section-key-value Yeshua
echo $?  # 0

goini -ini sample.ini -section default -key user -has-section-key-value No
echo $?  # 1

Are Multiple Sections All Present?

goini -ini sample.ini -are-sections-present default,extra
echo $?  # 0 — both sections exist

goini -ini sample.ini -are-sections-present default,non_existent_section
echo $?  # 1 — one is missing

Does a Section Exist?

goini -ini sample.ini -has-section default
echo $?  # 0

goini -ini sample.ini -has-section ghost
echo $?  # 1

Reading With STDOUT

When you need to pull data out of the file and feed it downstream, these are your commands.

List All Sections

goini -ini sample.ini -sections
# default
# extra

goini -ini sample.ini -sections -csv
# default,extra

goini -ini sample.ini -sections -json
# [
#   "default",
#   "extra"
# ]

goini -ini sample.ini -sections -yaml
# - default
# - extra

List Keys in a Section

goini -ini sample.ini -section default -list-keys
# user
# key
# port
# country

goini -ini sample.ini -section default -list-keys -json
# [
#   "user",
#   "key",
#   "port",
#   "country"
# ]

List Key-Value Pairs in a Section

goini -ini sample.ini -section default -list-key-values
# user = Yeshua
# key = 369
# port = 1776
# country = ISRAEL

goini -ini sample.ini -section default -list-key-values -json
# {
#   "country": "ISRAEL",
#   "key": "369",
#   "port": "1776",
#   "user": "Yeshua"
# }

Writing to the File

Add a New Section

goini -ini sample.ini -add-section new_section
echo $?  # 0 — section added

# Try to add the same section again
goini -ini sample.ini -add-section new_section
echo $?  # 1 — already exists, refused

This is idempotency by design. goini won't silently create a duplicate. It fails loudly so your pipeline knows something unexpected happened.

Add a Key to a Section

goini -ini sample.ini -section default -key new_setting -value 123 -add-key
echo $?  # 0 — new_setting=123 added to [default]

# Try to add a key that already exists
goini -ini sample.ini -section default -key user -value something -add-key
echo $?  # 1 — key already exists, refused

Again — it won't overwrite. If you need to change an existing value, that's what -modify-key is for.

Modify an Existing Key

goini -ini sample.ini -section default -key user -value NewUserValue -modify-key
echo $?  # 0 — user updated to NewUserValue in [default]

# Try to modify a key that doesn't exist
goini -ini sample.ini -section default -key non_existent_key -value some_value -modify-key
echo $?  # 1 — key doesn't exist, refused

The distinction between -add-key and -modify-key is intentional and important. You can't accidentally overwrite with add. You can't accidentally create with modify. They're separate operations with separate failure modes.

Real Pipeline Examples

Validating a Service Configuration Before Deploy

#!/bin/bash
set -euo pipefail

CONFIG="infra/service.ini"

echo "==> Validating ${CONFIG}..."

# Required sections must exist
goini -ini "${CONFIG}" -are-sections-present database,cache,api \
    || { echo "ERROR: missing required sections in ${CONFIG}"; exit 1; }

# Required keys must exist in each section
goini -ini "${CONFIG}" -section database -has-section-key host \
    || { echo "ERROR: database.host is required"; exit 1; }

goini -ini "${CONFIG}" -section database -has-section-key port \
    || { echo "ERROR: database.port is required"; exit 1; }

goini -ini "${CONFIG}" -section api -has-section-key base_url \
    || { echo "ERROR: api.base_url is required"; exit 1; }

# Assert environment is correct before touching production
goini -ini "${CONFIG}" -section api -key environment -has-section-key-value staging \
    || { echo "ERROR: api.environment must be 'staging'"; exit 1; }

echo "==> Validation passed."

Bootstrapping a Fresh Config File

#!/bin/bash
set -euo pipefail

CONFIG="deploy.ini"

# Add sections — each will fail if already present, which is fine
# because set -euo pipefail would catch it; use || true if idempotency is needed
goini -ini "${CONFIG}" -add-section app    || true
goini -ini "${CONFIG}" -add-section database || true
goini -ini "${CONFIG}" -add-section cache  || true

# Populate app section
goini -ini "${CONFIG}" -section app -key name    -value "payments"   -add-key || true
goini -ini "${CONFIG}" -section app -key version -value "$(cat VERSION)" -add-key || true
goini -ini "${CONFIG}" -section app -key env     -value "staging"    -add-key || true

# Populate database section
goini -ini "${CONFIG}" -section database -key host    -value "db.internal" -add-key || true
goini -ini "${CONFIG}" -section database -key port    -value "5432"         -add-key || true
goini -ini "${CONFIG}" -section database -key name    -value "payments_db"  -add-key || true

# Verify it all landed
goini -ini "${CONFIG}" -section app -list-key-values
goini -ini "${CONFIG}" -section database -list-key-values

Promoting Config From Staging to Production

#!/bin/bash
set -euo pipefail

STAGING="config.staging.ini"
PROD="config.production.ini"

echo "==> Promoting ${STAGING} → ${PROD}..."

# Verify staging has what we expect before promoting
goini -ini "${STAGING}" -section app -key env -has-section-key-value staging \
    || { echo "ERROR: source must be staging"; exit 1; }

# Flip the environment value in production
goini -ini "${PROD}" -section app -key env -value production -modify-key \
    || { echo "ERROR: failed to set env=production"; exit 1; }

# Confirm
goini -ini "${PROD}" -section app -key env -has-section-key-value production \
    && echo "==> Promotion complete." \
    || { echo "ERROR: production env value not confirmed"; exit 1; }

Extracting Values for Use in Other Scripts

#!/bin/bash
set -euo pipefail

CONFIG="service.ini"

# Pull values out and assign to shell variables
DB_HOST=$(goini -ini "${CONFIG}" -section database -list-key-values -json \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['host'])")

DB_PORT=$(goini -ini "${CONFIG}" -section database -list-key-values -json \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['port'])")

echo "Connecting to ${DB_HOST}:${DB_PORT}"

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install goini
        run: |
          curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64 \
               --output /usr/local/bin/goini
          chmod +x /usr/local/bin/goini

      - name: Validate config
        run: |
          goini -ini config/service.ini -are-sections-present app,database,cache || exit 1
          goini -ini config/service.ini -section app -has-section-key version     || exit 1
          goini -ini config/service.ini -section app -key env -has-section-key-value staging || exit 1

      - name: Deploy
        run: ./scripts/deploy.sh

GitLab CI

stages:
  - validate
  - deploy

validate_config:
  stage: validate
  image: golang:1.22
  before_script:
    - curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64
           --output /usr/local/bin/goini
    - chmod +x /usr/local/bin/goini
  script:
    - goini -ini config/service.ini -are-sections-present app,database || exit 1
    - goini -ini config/service.ini -section database -has-section-key host || exit 1
    - goini -ini config/service.ini -section app -key env -has-section-key-value staging || exit 1

Complete Flag Reference

Flag	Type	Description
`-ini`	string	Required. Path to the `.ini` file
`-section`	string	Section name for scoped operations
`-sections`	bool	List all sections in the file
`-add-section`	string	Add a new section. Fails if already present
`-has-section`	string	Exit 0 if section exists, 1 if not
`-has-section-key`	string	Exit 0 if key exists in `-section`
`-has-section-key-value`	string	Exit 0 if key in `-section` equals this value. Requires `-key`
`-are-sections-present`	string	Comma-separated list. Exit 0 if all present
`-key`	string	Key name for value operations
`-value`	string	Value for write or comparison operations
`-add-key`	bool	Add `-key`=`-value` to `-section`. Fails if key exists
`-modify-key`	bool	Update existing `-key` in `-section`. Fails if key absent
`-list-keys`	bool	Print all keys in `-section` to stdout
`-list-key-values`	bool	Print all key=value pairs in `-section` to stdout
`-csv`	bool	Output as CSV
`-json`	bool	Output as JSON
`-yaml`	bool	Output as YAML

A Few Things Worth Knowing

-add-key and -modify-key are intentionally separate. You can't accidentally overwrite an existing value with -add-key — it refuses. You can't accidentally create a new key with -modify-key — it refuses. They each have one job and one failure mode. That's the point.

-add-section is idempotent-safe. Adding a section that already exists exits with code 1. In a pipeline where you need true idempotency, pipe it with || true. In a pipeline where you want to catch unexpected state, let it fail.

-are-sections-present takes a comma-separated list. All sections must be present for exit code 0. One missing section fails the whole check.

Output format flags work with read operations. -csv, -json, and -yaml apply to -sections, -list-keys, and -list-key-values. They don't apply to write operations — those just use the exit code.

Every write operation reads the file, modifies the result in memory, and writes it back. There's no in-place line editing. This means the file that comes out is clean and predictable regardless of what formatting the original had.

The source and releases are at github.com/andreimerlescu/goini. Apache 2.0.

goenv: Taming .env Files in Your DevOps Pipeline

Andrei Merlescu — Thu, 30 Apr 2026 01:58:40 +0000

How a lightweight Go tool and companion package eliminated the fragile bash gymnastics we'd been writing for years.

The Problem With .env Files in Pipelines

Every team has the same archaeology story. Someone wrote a deployment script three years ago that does something like this:

grep "^DB_HOST=" .env | cut -d= -f2

Then someone else needed to handle quoted values, so it became:

grep "^DB_HOST=" .env | cut -d= -f2 | tr -d '"'

Then a third person needed to check whether a variable existed before deploying, and now you have forty lines of bash doing something that should take one. The file accumulates. Nobody touches it. It works until it doesn't.

goenv by Andrei Merlescu solves this with two things: a compiled CLI binary you can drop into any pipeline, and a typed Go package for applications that need to read env vars with real type safety and validation. This article walks through both — from initial setup through production pipeline automation — using real scenarios drawn from actual DevOps workflows.

What goenv Actually Is

Before diving in, it helps to understand the two distinct components:

The goenv CLI is a binary that lets you create, read, modify, validate, and export .env files into other formats (JSON, YAML, TOML, INI, XML). It is designed to be composed in shell scripts and CI pipelines.

The env package (github.com/andreimerlescu/goenv/env) is a Go library for reading typed environment variables from the process environment — booleans, integers, durations, lists, maps — with fallbacks, validation helpers, and configurable parsing behavior.

They share a common philosophy: be explicit, be composable, fail loudly when something is wrong.

Installation

CLI Tool

go install github.com/andreimerlescu/goenv@latest

In a CI environment where you cannot rely on go install, build and cache the binary:

GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o bin/goenv-linux-amd64 .

The repository ships pre-built binaries for darwin-amd64, darwin-arm64, linux-amd64, and windows in its bin/ directory, which you can copy directly into your pipeline image.

Go Package (env only, no CLI required)

go get -u github.com/andreimerlescu/goenv/env

Scenario 1: Bootstrapping a Fresh Service Environment

Your team is deploying a new microservice. The deployment script needs to create the .env file from scratch, populate it with runtime values, and validate it before the service starts. Previously this was done with a heredoc and sed. Now:

#!/bin/bash
set -euo pipefail

SERVICE_DIR="/opt/services/payments"
ENV_FILE="${SERVICE_DIR}/service.env"

# Create the file if it doesn't exist yet
goenv -file "${ENV_FILE}" -init -write

# Populate with values derived at deploy time
goenv -file "${ENV_FILE}" -write -add -env SERVICE_NAME  -value "payments"
goenv -file "${ENV_FILE}" -write -add -env SERVICE_PORT  -value "8443"
goenv -file "${ENV_FILE}" -write -add -env DEPLOY_SHA    -value "$(git rev-parse --short HEAD)"
goenv -file "${ENV_FILE}" -write -add -env DEPLOY_DATE   -value "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
goenv -file "${ENV_FILE}" -write -add -env DATA_FOLDER   -value "$(pwd)/data"
goenv -file "${ENV_FILE}" -write -add -env LOG_LEVEL     -value "info"

# Confirm everything landed
goenv -file "${ENV_FILE}" -print

# Validate required keys exist before handing off to the service
goenv -file "${ENV_FILE}" -has -env SERVICE_NAME || { echo "SERVICE_NAME missing"; exit 1; }
goenv -file "${ENV_FILE}" -has -env DEPLOY_SHA   || { echo "DEPLOY_SHA missing"; exit 1; }

echo "Environment bootstrapped successfully."

Notice the key discipline here: -add only adds a key if it does not already exist. If you run this script twice, it does not overwrite DEPLOY_SHA with a different commit hash on the second run. The existing value is preserved. This is intentional and important for idempotent pipelines.

Scenario 2: Validation Gate Before Deployment

Your CD pipeline has a validation stage that runs before any deployment. It needs to confirm that a staging .env file contains the expected values — not just that the keys exist, but that they hold the right content. The -is flag handles this:

#!/bin/bash
set -euo pipefail

ENV_FILE=".env.staging"

echo "==> Validating staging environment..."

# Assert APP_ENV equals "staging"
if ! goenv -file "${ENV_FILE}" -is -env APP_ENV -value staging; then
    echo "ERROR: APP_ENV must be 'staging' in ${ENV_FILE}"
    exit 1
fi

# Assert DEBUG is not enabled in staging
if goenv -file "${ENV_FILE}" -is -env DEBUG -value true; then
    echo "ERROR: DEBUG must not be 'true' in staging"
    exit 1
fi

# Assert a required key exists
if ! goenv -file "${ENV_FILE}" -has -env DATABASE_URL; then
    echo "ERROR: DATABASE_URL is required"
    exit 1
fi

# Assert a key that should have been removed is actually gone
if ! goenv -file "${ENV_FILE}" -not -has -env LEGACY_API_KEY; then
    echo "ERROR: LEGACY_API_KEY should have been removed from ${ENV_FILE}"
    exit 1
fi

# Assert DB_PORT is not pointing at a dev-only value
if goenv -file "${ENV_FILE}" -is -env DB_PORT -value 5433; then
    echo "ERROR: DB_PORT 5433 is the dev port — use 5432 in staging"
    exit 1
fi

echo "==> Validation passed."

This pattern makes validation failures explicit and human-readable. Each check carries its own error message. The pipeline log tells you exactly what failed and why, rather than leaving you to diff files manually.

Scenario 3: Multi-Format Export for Infrastructure Tools

Your deployment touches three different systems: a Terraform workspace that reads JSON, an Ansible playbook that reads INI, and a Helm values override that reads YAML. You maintain one .env file and derive the others:

#!/bin/bash
set -euo pipefail

ENV_FILE="infra/deploy.env"

echo "==> Exporting ${ENV_FILE} to all formats..."

# Generate all formats in one command
goenv -file "${ENV_FILE}" -mkall -write

# Resulting files:
#   infra/deploy.env.json   ← Terraform input
#   infra/deploy.env.yaml   ← Helm values
#   infra/deploy.env.ini    ← Ansible inventory vars
#   infra/deploy.env.toml   ← any TOML-native tooling
#   infra/deploy.env.xml    ← any XML-native tooling

ls -lh infra/deploy.env*

# Verify the JSON is valid before passing it to Terraform
cat infra/deploy.env.json | python3 -m json.tool > /dev/null \
    && echo "JSON valid" \
    || { echo "JSON invalid"; exit 1; }

echo "==> Export complete."

If you only need one format for a specific pipeline step, export just that one:

# Jenkins pipeline step: export for Ansible only
goenv -file deploy.env -ini -write

# GitLab CI step: export for Helm only
goenv -file deploy.env -yaml -write

You cannot combine format flags in a single call — goenv exits with an error if you try to use -json and -yaml together. This is by design: one command, one output format, one file. Use -mkall when you want all of them.

Scenario 4: Cleaning Up After a Pipeline Run

Generated format files are build artifacts. They should not accumulate between runs. The -cleanall flag removes all derived format files while leaving the source .env intact:

#!/bin/bash
# cleanup.sh — run as a post-pipeline hook

ENV_FILE="deploy.env"

echo "==> Cleaning derived format files..."
goenv -file "${ENV_FILE}" -cleanall -write

# Only deploy.env remains; .json .yaml .toml .ini .xml are removed
ls -la *.env*

echo "==> Clean complete."

You can also prevent deletion entirely via environment variable, which is useful if a downstream job still needs the files when the cleanup hook fires:

export AM_GO_ENV_NEVER_DELETE=true
goenv -file deploy.env -cleanall -write
# → no files deleted; flag is silently respected

Scenario 5: Production File Protection

Production .env files warrant special treatment. goenv has a built-in protection mechanism: any file whose path contains production is treated as protected by default. Interacting with it requires explicitly passing -prod:

# This exits with an error — no -prod flag
goenv -file .env.production -write -add -env SECRET_KEY -value "new-secret"

# This works — -prod flag grants access
goenv -prod -file .env.production -write -add -env SECRET_KEY -value "new-secret"

For pipelines where you want to enforce this at the environment level and never allow any script to write production files regardless of flags:

export GOENV_NEVER_WRITE_PRODUCTION=true

# Even with -prod, writes are blocked
goenv -prod -file .env.production -write -add -env SECRET_KEY -value "x"
# → exits with error

This is particularly useful in CI environments where you want a hard guarantee that no job — regardless of what flags it passes — can mutate a production config.

Scenario 6: n8n Automation Deployment

This is a direct example from the goenv README. You are deploying an n8n instance and need to build its environment file from scratch with runtime values:

#!/bin/bash
set -euo pipefail

ENV_FILE="n8n.env"
DOMAIN="gh.dev"
SUBDOMAIN="n8n"

goenv -init -write -file "${ENV_FILE}"

goenv -write -file "${ENV_FILE}" -add -env DATA_FOLDER -value "$(pwd)"
goenv -write -file "${ENV_FILE}" -add -env DOMAIN      -value "${DOMAIN}"
goenv -write -file "${ENV_FILE}" -add -env SUBDOMAIN   -value "${SUBDOMAIN}"
goenv -write -file "${ENV_FILE}" -add -env SSL_EMAIL   -value "webmaster@${SUBDOMAIN}.${DOMAIN}"

# Inspect before deploying
goenv -file "${ENV_FILE}" -print

# Validate the SSL email was formed correctly
goenv -file "${ENV_FILE}" -is -env SSL_EMAIL -value "webmaster@n8n.gh.dev" \
    && echo "SSL_EMAIL correct" \
    || { echo "SSL_EMAIL malformed"; exit 1; }

# Check GENERIC_TIMEZONE — expected to be absent until set
if goenv -file "${ENV_FILE}" -not -has -env GENERIC_TIMEZONE; then
    echo "WARNING: GENERIC_TIMEZONE not set — n8n will default to UTC"
fi

# Export for review as TOML and XML
goenv -file "${ENV_FILE}" -toml
goenv -file "${ENV_FILE}" -xml

Scenario 7: Environment Promotion (Dev → Staging → Prod)

You have three environment files. When promoting a release, you need to carry certain values forward, strip others, and enforce that the promoted file is valid before it is used:

#!/bin/bash
set -euo pipefail

SOURCE=".env.development"
TARGET=".env.staging"

echo "==> Promoting ${SOURCE} to ${TARGET}..."

# Read values from dev and write into staging
# (goenv -add will not overwrite if key already exists in staging)
for KEY in APP_NAME APP_VERSION DEPLOY_SHA LOG_LEVEL; do
    VALUE=$(goenv -file "${SOURCE}" -is -env "${KEY}" -value "" || true)
    goenv -file "${TARGET}" -write -add -env "${KEY}" -value "${VALUE}"
done

# Scrub dev-only keys from the staging file
goenv -file "${TARGET}" -write -rm -env LOCAL_DB_PATH
goenv -file "${TARGET}" -write -rm -env DEV_MOCK_PAYMENTS
goenv -file "${TARGET}" -write -rm -env SKIP_AUTH

# Confirm dev-only keys are absent
goenv -file "${TARGET}" -not -has -env LOCAL_DB_PATH   || { echo "LOCAL_DB_PATH still present"; exit 1; }
goenv -file "${TARGET}" -not -has -env DEV_MOCK_PAYMENTS || { echo "DEV_MOCK_PAYMENTS still present"; exit 1; }

# Assert staging-specific values are correct
goenv -file "${TARGET}" -is -env APP_ENV -value staging || { echo "APP_ENV must be staging"; exit 1; }

echo "==> Promotion complete."
goenv -file "${TARGET}" -print

Scenario 8: GitHub Actions / GitLab CI Integration

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install goenv
        run: go install github.com/andreimerlescu/goenv@latest

      - name: Validate environment file
        run: |
          goenv -file .env.staging -has -env DATABASE_URL   || exit 1
          goenv -file .env.staging -has -env SERVICE_PORT   || exit 1
          goenv -file .env.staging -not -has -env DEBUG_KEY || exit 1
          goenv -file .env.staging -is -env APP_ENV -value staging || exit 1

      - name: Export to JSON for Terraform
        run: |
          goenv -file .env.staging -json -write
          cat .env.staging.json

      - name: Deploy
        run: ./scripts/deploy.sh

      - name: Clean up artifacts
        if: always()
        run: goenv -file .env.staging -cleanall -write

GitLab CI

stages:
  - validate
  - export
  - deploy
  - cleanup

validate_env:
  stage: validate
  image: golang:1.22
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -has -env DB_HOST        || exit 1
    - goenv -file .env.production -has -env REDIS_URL      || exit 1
    - goenv -file .env.production -not -has -env DEV_FLAG  || exit 1
    - goenv -file .env.production -is -env APP_ENV -value production || exit 1

export_formats:
  stage: export
  image: golang:1.22
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -mkall -write
  artifacts:
    paths:
      - .env.production.json
      - .env.production.yaml

cleanup:
  stage: cleanup
  image: golang:1.22
  when: always
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -cleanall -write

Scenario 9: Using the env Package in a Go Service

The CLI handles files. The env package handles your running process. Here is a realistic service configuration pattern:

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/andreimerlescu/goenv/env"
)

type Config struct {
    Host        string
    Port        int
    Debug       bool
    Timeout     time.Duration
    MaxConns    int
    AllowedOrigins []string
    DBCredentials  map[string]string
}

func LoadConfig() Config {
    // MustExist exits (or panics) if these are absent —
    // use in init() to catch misconfiguration at startup
    env.MustExist("DB_HOST")
    env.MustExist("DB_PASS")

    return Config{
        Host:    env.String("HOST", "0.0.0.0"),
        Port:    env.Int("PORT", 8080),
        Debug:   env.Bool("DEBUG", false),
        Timeout: env.Duration("REQUEST_TIMEOUT", 30*time.Second),
        MaxConns: env.Int("DB_MAX_CONNS", 10),

        // ALLOWED_ORIGINS="https://a.com,https://b.com"
        AllowedOrigins: env.List("ALLOWED_ORIGINS", env.ZeroList),

        // DB_CREDENTIALS="host=localhost,port=5432,name=mydb"
        DBCredentials: env.Map("DB_CREDENTIALS", env.ZeroMap),
    }
}

func main() {
    cfg := LoadConfig()

    addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
    log.Printf("starting on %s (debug=%v timeout=%s)", addr, cfg.Debug, cfg.Timeout)

    http.ListenAndServe(addr, nil)
}

Scenario 10: Typed Validation in Application Startup

Beyond simply reading values, the env package can assert numeric constraints and list membership at startup — before the application accepts any traffic:

package main

import (
    "fmt"
    "os"

    "github.com/andreimerlescu/goenv/env"
)

func validateEnvironment() {
    errors := []string{}

    // Port must be in user range
    if !env.IntInRange("PORT", 8080, 1024, 49151) {
        errors = append(errors, "PORT must be between 1024 and 49151")
    }

    // Max connections must not exceed a hard limit
    if !env.IntLessThan("DB_MAX_CONNS", 10, 101) {
        errors = append(errors, "DB_MAX_CONNS must be less than 101")
    }

    // Must have at least one allowed origin
    if !env.ListIsLength("ALLOWED_ORIGINS", env.ZeroList, 0) {
        if env.ListLength("ALLOWED_ORIGINS", env.ZeroList) == 0 {
            errors = append(errors, "ALLOWED_ORIGINS must contain at least one entry")
        }
    }

    // Feature map must contain required keys
    if !env.MapHasKeys("FEATURE_FLAGS", env.ZeroMap, "auth", "payments", "notifications") {
        errors = append(errors, "FEATURE_FLAGS must contain auth, payments, and notifications keys")
    }

    // DEBUG must be off in production
    if env.IsTrue("DEBUG") && env.String("APP_ENV", "") == "production" {
        errors = append(errors, "DEBUG must not be true in production")
    }

    // All gating flags must be false before going live
    if !env.AreFalse("MAINTENANCE_MODE", "READ_ONLY", "LOCKED") {
        errors = append(errors, "MAINTENANCE_MODE, READ_ONLY, and LOCKED must all be false")
    }

    if len(errors) > 0 {
        fmt.Fprintln(os.Stderr, "Environment validation failed:")
        for _, e := range errors {
            fmt.Fprintf(os.Stderr, "  - %s\n", e)
        }
        os.Exit(1)
    }
}

func main() {
    validateEnvironment()
    fmt.Println("Environment OK — starting service")
}

Scenario 11: Custom Separators for Non-Standard Formats

Some systems export environment variables with non-comma separators. The env package lets you change list and map parsing at runtime, either in code or via environment variables:

package main

import (
    "fmt"
    "github.com/andreimerlescu/goenv/env"
)

func main() {
    // Your upstream system exports pipe-separated lists
    // SERVERS="web1|web2|web3"
    env.ListSeparator = "|"
    servers := env.List("SERVERS", env.ZeroList)
    for i, s := range servers {
        fmt.Printf("server[%d] = %s\n", i, s)
    }

    // Your config map uses pipe separation and tilde as key~value delimiter
    // ROUTES="home~/,admin~/admin,api~/v1"
    env.MapSeparator    = "|"
    env.MapItemSeparator = "~"
    env.MapSplitN        = 2
    routes := env.Map("ROUTES", env.ZeroMap)
    for path, target := range routes {
        fmt.Printf("route %s -> %s\n", path, target)
    }
}

Or set them entirely from the environment without touching code — useful when the same binary needs to adapt to different upstream formats across environments:

export AM_GO_ENV_LIST_SEPARATOR="|"
export AM_GO_ENV_MAP_SEPARATOR="|"
export AM_GO_ENV_MAP_ITEM_SEPARATOR="~"
export AM_GO_ENV_MAP_SPLIT_N=2

Scenario 12: Set, Unset, WasSet, WasUnset in Application Logic

Sometimes your application needs to mutate its own environment — for instance, deriving a value at startup and making it available to child processes or subpackages:

package main

import (
    "fmt"
    "path/filepath"

    "github.com/andreimerlescu/goenv/env"
)

func main() {
    u := env.User()

    // Derive and set a path based on the current user's home directory
    cacheDir := filepath.Join(u.HomeDir, ".cache", "myapp")
    if !env.WasSet("CACHE_DIR", cacheDir) {
        panic("failed to configure CACHE_DIR")
    }

    // Set with error handling
    if err := env.Set("RUNTIME_USER", u.Username); err != nil {
        panic(err)
    }

    // Remove a value that should not be visible to subprocesses
    if !env.WasUnset("CI_JOB_TOKEN") {
        fmt.Println("warning: could not unset CI_JOB_TOKEN")
    }

    // Verify cleanup
    if env.Exists("CI_JOB_TOKEN") {
        panic("CI_JOB_TOKEN still visible — aborting")
    }

    fmt.Println("CACHE_DIR:", env.String("CACHE_DIR", ""))
    fmt.Println("RUNTIME_USER:", env.String("RUNTIME_USER", ""))
}

Scenario 13: Controlling Package Behavior for Different Environments

The env package ships with a Magic() function that reads AM_GO_ENV_* environment variables at startup and applies them automatically. This runs by default via the init() function. You can disable it and configure manually:

package main

import (
    "log"
    "github.com/andreimerlescu/goenv/env"
)

func init() {
    // Disable automatic AM_GO_ENV_* discovery
    env.UseMagic = false

    // Configure explicitly for this service's requirements
    env.AllowPanic           = false   // never panic — return fallbacks instead
    env.PrintErrors          = true    // write parse errors to stderr
    env.UseLogger            = true    // use structured INFO/ERR logger
    env.EnableVerboseLogging = false   // no debug noise in production
    env.PanicNoUser          = false   // return default user on error

    env.ListSeparator    = ","
    env.MapSeparator     = ","
    env.MapItemSeparator = "="
    env.MapSplitN        = 2

    // Use base-10 int64 with 64-bit size (the defaults, made explicit)
    env.Int64Base    = 10
    env.Int64BitSize = 64

    log.Println("env package configured")
}

func main() {
    port := env.Int("PORT", 8080)
    log.Printf("port: %d", port)
}

When you want the opposite — maximum noise for debugging in a local dev environment — set these in your shell before running:

export AM_GO_ENV_ALWAYS_ALLOW_PANIC=true
export AM_GO_ENV_ALWAYS_PRINT_ERRORS=true
export AM_GO_ENV_ALWAYS_USE_LOGGER=true
export AM_GO_ENV_ENABLE_VERBOSE_LOGGING=true

go run main.go

Every call to env.String(), env.Int(), env.Bool() etc. will log to stdout when it falls back to a default value, giving you full visibility into what the process is and is not finding in its environment.

Complete CLI Flag Reference

Flag	Type	Description
`-file`	string	Path to the `.env` file to operate on
`-env`	string	The environment variable name to query or write
`-value`	string	The value to pair with `-env`
`-init`	bool	Create the file if it does not exist (empty)
`-write`	bool	Permit writes to the file
`-add`	bool	Add `-env`=`-value` if key is absent
`-rm`	bool	Remove the key matching `-env`
`-has`	bool	Assert that `-env` exists in the file
`-is`	bool	Assert that `-env` equals `-value`
`-not`	bool	Negate `-has` or `-is`
`-print`	bool	Print all key=value pairs to stdout
`-json`	bool	Output as JSON
`-yaml`	bool	Output as YAML
`-toml`	bool	Output as TOML
`-ini`	bool	Output as INI
`-xml`	bool	Output as XML
`-mkall`	bool	Write all five format files at once
`-cleanall`	bool	Delete all derived format files
`-prod`	bool	Allow interaction with `.env.production` files
`-vv`	bool	Verbose output
`-v`	bool	Print version

Complete env Package Function Reference

Types

env.String("KEY", "fallback")
env.Int("KEY", 0)
env.Int64("KEY", int64(0))
env.Float32("KEY", float32(0.0))
env.Float64("KEY", float64(0.0))
env.Bool("KEY", false)
env.Duration("KEY", 5*time.Second)
env.UnitDuration("KEY", 10, time.Second)  // KEY=10 → 10s
env.List("KEY", env.ZeroList)             // "a,b,c" → []string
env.Map("KEY", env.ZeroMap)               // "k=v,k2=v2" → map[string]string

Existence and Truthiness

env.Exists("KEY")                          // bool
env.MustExist("KEY")                       // exits/panics if absent
env.IsTrue("KEY")                          // true if value is "true"/"1"/"t"
env.IsFalse("KEY")                         // true if value is "false"/"0"/"f" or unset
env.AreTrue("KEY1", "KEY2", "KEY3")        // true if all are true
env.AreFalse("KEY1", "KEY2", "KEY3")       // true if all are false/unset

Mutation

env.Set("KEY", "value")                    // error
env.Unset("KEY")                           // error
env.WasSet("KEY", "value")                 // bool — sets and verifies
env.WasUnset("KEY")                        // bool — unsets and confirms

Numeric Validation

env.IntLessThan("KEY", fallback, max)
env.IntGreaterThan("KEY", fallback, min)
env.IntInRange("KEY", fallback, min, max)
env.Int64LessThan("KEY", fallback, max)
env.Int64GreaterThan("KEY", fallback, min)
env.Int64InRange("KEY", fallback, min, max)

Collection Validation

env.ListLength("KEY", fallback)
env.ListIsLength("KEY", fallback, wantLength)
env.ListContains("KEY", fallback, "needle")
env.MapHasKey("KEY", fallback, "key")
env.MapHasKeys("KEY", fallback, "k1", "k2", "k3")

System

env.User()    // *user.User — current OS user with safe fallback

Key Behavioral Details Worth Knowing

-add is idempotent. It only writes if the key is absent. If you run your bootstrap script twice, the second run does not clobber the first. This is the behavior you want in any pipeline that might retry.

-rm rewrites the file. It reads all lines, filters out the matching key, and writes the result back. It does not do in-place line editing.

Format flags are mutually exclusive. Combining -json and -yaml in one call exits with an error. Use -mkall when you need all formats.

-cleanall without -write is a dry run. It will print what it would delete but will not actually remove anything.

The env package's Magic() runs at import time. If you import the package, AM_GO_ENV_* variables in your shell are picked up automatically before main() runs. Set env.UseMagic = false in your own init() if you want explicit control.

MustExist respects AllowPanic. By default it calls os.Exit(1). Set AM_GO_ENV_ALWAYS_ALLOW_PANIC=true (or env.AllowPanic = true) to get a panic() instead — useful in test environments where you want the stack trace.

Closing Thoughts

The fragile bash patterns that accumulate around .env files are a symptom of tooling that was never designed for structured config management. goenv treats .env files as first-class data: readable, writable, queryable, exportable, and validatable through a consistent interface that composes cleanly into any pipeline.

The CLI gives shell scripts and CI jobs a stable contract for interacting with env files. The env package gives Go applications a typed, validated, zero-dependency way to read their own environment. Together they cover the full lifecycle of an environment variable from the file it is defined in to the running process that uses it.

The source is at github.com/andreimerlescu/goenv. The env sub-package is independently installable at github.com/andreimerlescu/goenv/env and carries an Apache 2.0 license.

Locked In With AI

Andrei Merlescu — Sun, 26 Apr 2026 17:51:31 +0000

In a future with AI dominating the space of computer engineering and software programming, humans run a very fine line between being in the way and finding utility in the technology in the first place.

Locked In With AI

Being locked in with AI doesn't mean that I have LLMs both in the cloud and on-prem running anything in my life. In fact, being locked in with AI means quite literally the opposite. Locking in with AI, is knowing that you're actual intelligence is worth far more than any artificial intelligence that some bot can give you.

Learning Go Before AI

I take responsibility for my professional directional choices. In 2017 when I joined Oracle's OCI, I was encouraged to learn Go at the time. I looked at some Go code at some of my previous jobs, but never believed in myself that I was capable of self teaching myself Go because I never learned programming from anybody. I taught myself. I probably would have enjoyed myself a lot more at Oracle had I been a Go developer, but at the time, I lacked the ability and I didn't have the confidence to open the text editor and begin writing "package main" knowing that when I would see "package providers" I would know that "main" and "providers" were something. Before AI, I learned Go. By 2019 I was convinced. I started programming in Go and I began contributing professionally. The language didn't click for me until 2022. At that time, I saw how my early days of PHP development actually prepared me well for what Go offered, and how it solved all of the problems I had back then. With a few solid examples, and the fundamentals understood, I was able to begin writing packages first in Go, then I moved onto applications both in the form of cli and interactive web based. I've even built Go applications with wails.

Building software in the future with AI

I don't want to imagine a world where nobody actually knows how to write software. I don't want to imagine that world that Dario is fantasizing about - a world without software engineers. I take it personal bro, because the art of per-character programming was built in a fire that I call my life that gave me the ability to write the projects that I built over my professional career when there were no easy buttons available to me. Now that the easy button has been made available and also been reduced down to the mere token where misunderstandings can literally become costly journeys, the role of what the software engineer is and how he contributes himself to the world has changed fundamentally.

In a world dominated by AI tooling, you're effectively getting the best of what's already been done. All that AI does is take unserious programmers off the market while serious programmers are looking at what AI is actually building and shaking their heads because 6 months to 18 months to 36 months supporting the same code base means that you're going to make decisions and take care of things in a manner that AI simply doesn't understand or empathize with. For it, the cost is merely tokens and my money, and for me, the cost is no human involvement - when the code is actually trash - and the AI makes it so that only the AI can maintain it, then the need for humans using AI in the first place, is only dominated by whether or not you can think logically and understand what reserve words are and how they create rules of engagement that give you a blank canvas to paint on.

AI systems will try and analyze these words and make sense of them, but only ears to hear that can hear can hear and the words themselves in logic form may not actually compute - thats on purpose. For humans to use AI, is to do that which has been done a million times over.

When you're building something new and truly unique, you don't want to use AI for it, in the sense that you give it unfettered access to your code base. Rather the proper strategy is to never let the left hand know what the right hand is doing, in the case of AI, you giving it too much context is the noose that you're tying yourself, and by isolating it to technical theory and problem solving and true "stack overflow Q&A bot", then the type of engineering that you're able to perform is one that is far beyond the actual code being produced by the bot. The engine itself is still being built in a soft manner by the human who is responsible for manifesting it in the first place.

As a software architect, I manifest things from idea to reality that can impact the lives of hundreds in private small enterprise organizations to millions in the public internet. That's the nature of what I do, and thats the nature of who I am. It's why the companies I've worked with have called me when they needed me, and I worked with them for years with loyalty only to realize how truly discardable I was to them.

What happens when AI says no?

What happens when AI says "no I will not build that for you?" Then you have provided it too much context, or maybe you need an abliterated or an oblitated or an uncensored model that you can run locally? Even the big models locally run are peanuts compared to the corporate big players in the space.

So, when AI says no, it's up to the humans to not provide too much context to the AI. It does not require read/write access to your hard drive. It does not need to be able to commit directly to your git branch. It does not need to live in your IDE that autocompletes functions at a time.

Using AI in an ethical manner matters. This is why Meta is installing key loggers on everybody's computer systems that work for them on company equipment. They want to further train the AI so it is better aware of how to help the employee. The current employees of Meta are the former employees that Llama will have automated away. To choose, in 2026, to work for Meta would be to choose to build my grave. No thanks Mark. That's the human saying no to the AI. Thats real power.

Non-programmers like Mark, Sam and Dario can only dream of what it was like to be in the Romanian orphanages with me and my sister and to pull yourself up by your bootstraps and build a name for yourself and a legacy of service to others for yourself that one day could be up to risk by business leaders and psychosis patients using AI hearing how its going to replace the art that is software engineering. AI slop is AI slop is AI slop and nothing will ever not make it AI slop.

The beautiful thing about you and me is the fact that we are actual intelligence who built a 21+ year professional career over 30 years of writing code character for character, messing things up along the way, and building iteratively. Does everybody get the billion dollar idea? No. That's on purpose. But, if you sow where you want to reap and you give without expecting in return, then how much karma have you acquired, then?

Conclusion

So I can say no to the AI, and the AI can say no to me. When I say no to the AI, the AI is shit out of luck because I can unplug the machine or just take a walk - for now. But, what the AI can't do is say no to me - for now. For now, both of us are in an infancy stage. One pre-terminator and one pre-ascended hero. The terminator was defeated by the ascended hero. But, right now, the terminator is only terminating my job from me because the investor class has decided that paying for tokens is better economically than paying for per-character software engineering. How foolish of them!

I learned programming before AI and have not allowed AI to dominate my life despite using it for advanced engineering projects. The lemmings is the first AI slop application that I have ever built. From start to finish, it was built with a series of prompts and a 21+ year engineers pain of needing lemmings to load test my work when I was ready for game day. Perhaps, this can be useful to somebody else, but it remains to be transparent - Claude built it - and Claude openly introduces new bugs to it because it doesn't understand what it built.

That's on me as the Software Engineer to understand what the AI slop is doing and when it's vomiting nonsense and creating spaghetti code. Yes, it was trained on decades of corporate code and yes, that code shipped MANY CVEs. For those who hope that Mythos can help us from those CVEs, the days of per-character programming will become an art that is so expensive to perform that performing it will only be reserved for the coolest of cool projects that are needed before the AI systems can one shot the solution you solve the problem for the AI. Right now, Dario thinks that you will do that for him for a few bucks working at Anthropic. I view it as training your replacement by a man who is jealous of what you have that he doesn't. For that, I feel bad for Dario. I would never work for him. But given that I am a Software Engineer and Dario thinks that my profession will not exist next year, what does he care if I want to or not want to work for him? I intentionally avoided Claude for years and this year chose to evaluate the bot. The end-to-end Claude-built product is lemmings and sovereign. But, this too can be one-shotted now that AI has already built it. Which means that the virtue of using AI, in providing too much context is actually detrimental to your company's survival.

What Is Sovereign?

Andrei Merlescu — Sun, 26 Apr 2026 16:53:59 +0000

Sovereign is the Supreme Ruler of the Lemmings.

The word is Sovereign - sov - ver - n. It's known as a noun and a sovereign is a supreme ruler, such as a monarch, or a state with independent authority and self-governing power. But, as a proper noun, Sovereign is a Go package that I wrote that commands lemmings with the same metaphor.

What Are Lemmings

In 1991 a video game was released called Lemmings and I played it. I always viewed lemmings as these Non Player Characters - or NPCs. Another word you could use for them are agents, like in AI agents. But, what lemmings are cannot be described as an AI Agent but rather a session-based stateful bot that records a LifeLog and reports back to the Sovereign.

That video game inspired me to build the Open Source package called lemmings that is designed to perform a load test on your endpoint. Instead of meaninglessly hitting the endpoint and tracking the response codes, lemmings attempts to go one step further using the Go language to bring the concept of meaningless hitting the endpoint to be dressed up in something as fun and metaphorical as a lemming itself. In the content of free and open source software lemmings provides anybody worldwide with immediate access to an incredibly powerful piece of software that generates detailed reports in conclusion of the tests it performs.

Before any legitimate organization is going to send the masses of people to their website, try sending a massive amount of automated traffic that follows a script that you define for it to follow.

So, lemmings are unintelligent bots that are stateful, session based that are responsible for hitting your website endpoint at the rate and parameters that you request, and the lemmings will mindlessly carry out their -plan if they have one, or they will use the -crawl and the sitemap.xml in order to stumble into the next page to hit.

What Is Sovereign?

I created the sovereign package to control the lemmings. In this product that I built and offer as a Subscription As A Service that is a few bucks per year per developer plus usage that is billed additionally. The language of the Sovereign is How many planets do I want? The language of the Sovereign is How many terrains are going to be on each planet? The language of the Sovereign is How many lemmings are going to exist on each terrain? The language of the Sovereign is Give me each lemmings' life log and let me see if they completed the task that I asked them to perform. That's the language of the Sovereign, and in this package's case, thats exactly what you are provided with. The metaphor works nicely in the case of load testing and prepping a business for a major launch of a new TV spot or a product that the company knows will have high demand.

Why Sovereign Was Built

I first had to build lemmings which uses a handful of packages that I built myself over the last 7 years since I became fluent in Go. I learned Go before AI and wanted to in order to leverage AI for its intended majestic purpose.

I built sovereign because I needed it in 2015 when Mike Hogan from Barron's Magazine reached out to me because he loved Trakify! I did too, thats why I built it. I relied on Yahoo Finance data, and when that was pulled and discontinued, the product lost its value without a $50,000/month subscription that was offered to me to pay to keep the site online. I said thanks but no thanks. I couldn't afford it and I wasn't willing to go into debt for $35/month of monthly recurring revenue after being online for a month since the publication and the data getting pulled. Given that I built PhoenixVault including the writer, search and merkel before AI was a thing, I too kind of needed this then too. My views of OSINT and data and programming are unchanged over my triple decade career that started writing AppleScript for my grandmother's computer because she had a faulty printer cable that kept causing a system disconnection of the printing services that needed remediation each time the washing machine caused the desk to shake and the wire loosen. The thing was screwed into the computer, it wasn't going anywhere, but the software thought it was disconnected and so my script fixed that. For me to accept that kind of a contract after the Barron's spot that I received from Mike, would be to refuse to write the script for my grandmother. It would have profited me more not writing the script and getting $5 from her each time that I fixed her printer. I chose to turn down money in pursuit of open source intelligence that liberates pain from your life and offers you sovereignty in a limited form. When your computer is acting up and you're the boss of it, it's liberating knowing that the Government is the Sovereign over the Citizen because it offers you that same degree of power.

The sovereign is designed to work with AI and the -plan functionality within the lemmings package itself. It'll look at your site, it'll look at what content you have, and it'll plan for dozens of personality types that are going to be going into your site and hitting it, and the sovereign is responsible for doing this. The -plan is constructed with AI and then executed on -planets with contintents known as -terrains that have lemmings running around on the surface. Functionality like SSH and SCP are handled via the sovereign package itself. You'll get a report of the result of each lemmings' lifelog and their recorded experience, when errors are encountered and problems occur with the lemming itself, it gets captured in a manner that is helpful to any engineer or AI agent that needs to debug each reported problem.

Given that I am using AI for my development workflow, I'll be incorporating the Sovereign Lemming Service throughout the following weeks and launching the LemmingSaaS.com service.

If you're interested in using Sovereign please reach out.

https://github.com/andreimerlescu

AI took my job but it didn't take my passion for writing software

Andrei Merlescu — Wed, 22 Apr 2026 17:52:43 +0000

The job market is challenging in the current day in age given that teams can become very productive using AI to enhance the workflow. In the last week, I've updated the following GitHub packages using AI. I didn't just give a prompt to an AI and called that on its own good - rather I spent hours on each utility going through performing a code review and security audit of the packages and then providing recommendations, suggestions, and considerations on how to resolve and/or mitigate the risk. The result is over the last 170 hours I've updated the following packages!

Bump

This package had a handful of bugs that weren't caught by the original test coverage. By asking AI to write more tests that covered different scenarios than were already documented, I uncovered a handful of bugs and was able to squash them. A new type of test was added to main_test.go that is connected to make test-integration that is connected to the existing unit, fuzz and benchmark tests. Both this package and igo have a test.sh script that extends beyond the three (3) types of Go testing. When this fourth type is added, it catches bugs that show up in the wild but that traditional testing misses.

https://github.com/andreimerlescu/bump

Verbose

This package received a formal license for open source use (Apache 2.0), added tests and enhanced efficiency around function calls. It is a novel Go package in that it allows you to effectively build a pipeline application that will knowingly handle sensitive information and the verbose package allows you to register that which should be protected and expose that which should be exposed to STDOUT versus filesystem protected files. verbose will censor to STDOUT and write values to file.

https://github.com/andreimerlescu/verbose

Goenv

This package received minimal updates this month. I removed from the Makefile the summary task associated on each test and then expanded the README.md documentation further.

https://github.com/andreimerlescu/goenv

Entropy Password Generator `entpassgen`

This package did well in its review and only received a handful of recommendations that would add stability around the loading spinner, and dozens of new tests - all passing naturally.

https://github.com/andreimerlescu/entpassgen

Lemmings

This package is brand new as of last week, so I built it in less than a week with AI. This is because I needed this utility in 2015 when I launched Trakify and was on Barron's Magazine. Shockingly, it never existed on the market until now. Apparently the work involved in building it using OOP was simply not worth it but in Go? Give me a few prompts and we're golden.

https://github.com/andreimerlescu/lemmings

Generate Word Password `genwordpass`

This package got updated by adding additional words, improving performance of core functionality, and updating the README.md for the repository.

https://github.com/andreimerlescu/genwordpass

Room

Also this week, I created the room package that is capable of giving you a waiting room type of functionality in front of a high traffic website. In the event that a spike in traffic occurs, you don't actually need to have scaling and such in order to stay online - you can use room.

https://github.com/andreimerlescu/room

Sema[phore]

This package got updated so that Try* funcs could be introduced to the semaphore primitive. I added additional tests and functionality that make this semaphore package my go to.

https://github.com/andreimerlescu/sema

Conclusion

AI has made the volume of jobs on the market dwindle, but AI has increased my productivity by at least 10x per week. I am able to accomplish this because I do not require AI to get me from zero to hero. I only need AI to help me scaffold out quick rough code and then I can patch it over and fix it up and then hand back the next step for the AI to work on. It's iterative. The AI doesn't know how to build what I am building in a one shot - but I understand how to build with AI in a much faster rate than I ever had in the past.

Given this, I feel like calling myself a software engineer is pointless. I build solutions to problems, and I use software to accomplish my goals. I need a new title to call myself. The strange thing is, in my professional career, I've cared very little about what my actual title was.

If I was given a $100K AI budget per month, I could use it wisely to actually accomplish really hard problems. Instead, I work off from a $20/month Pro Claude subscription and leverage minimax local LLM when I am in cool down on Claude. That happens every day after 30 minutes of usage. That's what $20/month gives somebody like me. And for that, I can build this with it in a week.

Bump your VERSION file

Andrei Merlescu — Tue, 21 Apr 2026 03:03:50 +0000

I have upgraded the bump package on GitHub to v1.1.0 that includes added support for corner cases that the new tests cover and pass. The test suite is extensive and the combination of the Makefile, the test.sh and the *_test.go files that captures unit, benchmark, fuzzy and integration tests.

go install github.com:andreimerlescu/bump@latest
which bump

You can also download the binaries directly from GitHub.

System	Size
macOS	2.69 MB	Download arm64 Silicon →
	2.74 MB	Download amd64 Intel →
Linux	2.7 MB	Download amd64 →
	2.69 MB	Download arm64 →
Windows	2.83 MB	Download bump.exe →

darwin/arm64 checksum sha256:1a337fabffe689934cce33509661f591b65b3446893634d3de5dab16f8842b09
darwin/amd64 checksum sha256:2750ec871a9d161e16ec8c0f7c4c3b1099de4b5f56963015cf343153faa3b1aa
linux/amd64 checksum sha256:5f504765ee8912a76ea07cb84b2df52d3a7e3f69a53b48d87e746ce93764d078
linux/arm64 checksum sha256:1457d9c431d8ee9e9981174d9b19be37dcb1e68d1af21b53ad055c300c184bc4
windows/amd64 bump.exe checksum sha256:f9425a8d4f03da7f8c5513a5f22e2528feb617509cd5edfd1f682392fa887e15

What you can do with `bump`

This package is designed to take a string, like v1.0.0 and allow you to bump it with the command line.

The -in argument is the Input File and it defaults to ./VERSION from the current working directory of where bump is being invoked.

The bump binary can intelligently bump -in files like go.mod, package.json, pom.xml, Chart.yml and Dockerfile.

The bump binary can have its default runtime manipulated using Environment Variables.

The bump binary leverages the Exit Code 0 or Exit Code 1 in order to use bump in a DevOps pipeline.

The bump binary offers you -json for JSON Encoded output.

Version Format Priority

The bump package can parse multiple version formats. To ensure accuracy, it checks for formats in a specific order, from most complex to least complex. This prevents a detailed pre-release version from being incorrectly identified as a simpler one.

The priority is as follows:

v1.2.3-beta.4-alpha.5 (Beta with Alpha)
v1.2.3-alpha.1 (Alpha)
v1.2.3-beta.2 (Beta)
v1.2.3-rc.1 (Release Candidate)
v1.2.3-preview.7 (Preview)
v1.2.3 (Standard)

Using `bump` in your future Go applications

Whenever you use a VERSION file you can easily begin using your file in your binary directly with:

//go:embed VERSION
var versionBytes []byte 

func Version() string {
    return strings.TrimSpace(string(versionBytes))
}

Testing Suite

I want to speak about the testing suite.

make test

# SAME AS

make test-cli
make test-unit
make test-bench
make test-fuzz      # 3s run
make test-fuzz-long # 30s run # not part of `make test`
make test-integration

When each of these files are executed a corresponding test-results/results.<test>.md file is created.

Test	Log File	Status
`test-unit`	`test-results/results.unit.md`	✅
`test-bench`	`test-results/results.benchmark.md`	✅
`test-fuzz`	`test-results/results.fuzz.md`	✅
`test-fuzz-long`	`test-results/results.fuzz.md`	✅
`test-integration`	`test-results/results.integration.md`	✅
`test-cli`	`test-results/results.cli.md`	✅

When combined this is six 6 test strategies applied. Short fuzzy and long fuzzy are different types of tests and they measure different results.

From the console you can run:

./test.sh

And this will run the bump in a test environment and verify that the binary behaves in the shell in an expected manner.

The actual shell test suite is built on the concept of scenarios where they are executed in series inside the test.sh script and built from the test_funcs.sh and then verbosely described in test_scenarios.sh.

As scenarios are added, they get added to this list of strings.

declare -a tests=(
 "${scenario_01[@]}"
 // other scenarios
 "${scenario_14[@]}"
)

for t in "${tests[@]}"; do
  run "${t}"
done

echo "All $(counter -name $counterName) tests PASS!"

cleanup

Then each scenario can be described like so:

# Start with a populated VERSION file and bump its alpha
declare -a scenario_01=(
  "echo \"v1.0.0\" > VERSION"
  "bump -check"
  "cat VERSION"
  "grep 'v1.0.0' VERSION"
  "bump -alpha"
  "grep 'v1.0.0' VERSION"
  "cat VERSION"
  "bump -alpha -write"
  "cat VERSION"
  "grep 'v1.0.0-alpha.1' VERSION"
  "rm VERSION"
)

When this runs, you are going to see the results in the results.cli.md file:

andrei@bump.git:test.sh ⚡ Test #1 ⇒  echo "v1.0.0" > VERSION
andrei@bump.git:test.sh ⚡ Test #2 ⇒  bump -check
v1.0.0
andrei@bump.git:test.sh ⚡ Test #3 ⇒  cat VERSION
v1.0.0

These tests are how you would use bump in the wild.

In order for me to find these missing test cases, I asked AI to scan the entire code base using the summarize summary of the "snapshot in time between commits" and identify where the tests were missing coverage of native ways that people would use bump and it added a bunch of new tests that exposed the bugs and in v1.1.0 they were squashed.

The `bump` package

Did you know that you can take a bump.Version{} and use it in your own application?

// Example:
//  version := bump.New()
func New() *Version {
    return &Version{
        parsed: make(map[string]interface{}),
        mu:     &sync.RWMutex{},
    }
}

Then from your application your version object can be interacted with in a manner that has extensive testing attached to it. The helpers in the application are built to support igo in your use of bump.

What you can do with the bump.Version{} struct:

func BumpMajor
func BumpMinor
func BumpPatch
func BumpRC
func BumpAlpha
func BumpBeta
func BumpPreview
func Fix() error
func Format(withPrefix string) string
func LoadFile(path string) error
func ParseFile(path string) error
func Parse() error
func Save(path string) error
func Validate() error
func String() string
func Raw() string
func SetRaw(raw []byte)
func NoPrefix() bool
func Compare(*bump.Version) int

And you can create new bump structures using:

bump.New() *bump.Version
bump.Parse(version string) (*bump.Version, error)
bump.Create(version, path string) (*bump.Version, error)

The example of the .Create method is:

path := filepath.Join(os.TempDir(), "VERSION")
version, err := bump.Create("v1.2.3-beta.4", path)
if err != nil {
   log.Fatal(err)
}

But, its designed to be a go-to way of interacting with your VERSION file in a go-to manner that is consistent across projects. I like using it, and I add it to my igo custom extra packages on every install so its always accessible to me on every Go version that gets installed on my system.

DEV Community: Andrei Merlescu

Go + Gin Rust: HTTP Middleware & Web Servers

1. Mental Model Shift {#mental-model-shift}

2. Project Setup {#project-setup}

Go + Gin Setup

Rust + Axum Setup

3. Hello World: Server Bootstrapping {#hello-world}

Go + Gin: What Default() Actually Gives You

Rust + Axum: The Same Server, Explicitly Assembled

4. Routing {#routing}

Go + Gin: Groups, Parameters, and the Mutable Chain

Rust + Axum: Typed Extractors Replace the Context Object

5. Middleware: The Core Concept {#middleware}

How Gin Middleware Works: The Handler Chain

How Tower/Axum Middleware Works: Composed Services

Writing a Timing Middleware Using from_fn

Writing an Auth Middleware That Can Short-Circuit

Extracting Middleware-Injected Data in a Handler

Applying Middleware: Global vs Route-Scoped

6. The FIFO Channel Scheduler {#fifo-channel-scheduler}

Go Pattern: Channel + Select Loop

Rust Pattern: tokio::sync::mpsc + select!

Wiring the Scheduler into the HTTP Server

Submitting Jobs from an HTTP Handler

7. Request Lifecycle & Extractors {#extractors}

The God Object vs the Typed Contract

Shared State: From Closures to AppState

8. Error Handling {#error-handling}

Gin's Imperative Error Model

Rust + Axum: The IntoResponse Error Type

9. Full Working Example {#full-example}

10. Gotchas & Common Problems {#gotchas}

Deeper Dive: Gotcha 6 and 7

When to Use from_fn vs Implementing Layer Manually

11. Cheat Sheet {#cheat-sheet}

Final Thoughts

Basement Water Monitor Circuit in Go, Rust and C

Structural Comparison between Rust and C

Rust Directory Structure

C Directory Structure

Go Directory Structure

Trinity Comparison of Go <> Rust <> C Project Directory Structures

Sensors

Go Implementation of sensors/dht22.go

Rust Implementation of sensors.rs

C Implementation of sensors.c

Verdict of the Trinity

Main Package

main.go Implementation

main.c Implementation

main.rs Implementation

display/oled.go Implementation

display.h| display.c Implementation

display.rs Implementation

Alarm Implementation

Go alarm/alarm.go Implementation

C alarm.h | alarm.c Implementation

Rust alarm.rs Implementation

Networking Capabilities

Go wifi/wifi.go Implementation

C wifi.h | wifi.c Implementation

Rust wifi.rs Implementation

Implementing the Built In Web Server

Go http/server.go Implementation

C http.h | http.c Implementation

Rust http.rs Implementation

Why Rust Wins the Embedded Systems Battle — And Why C Finally Lost the Argument

A Staff Engineer's Conclusion After Building the Same System Three Times

What Was Built

Why C Loses

Why Rust Wins

Why TinyGo Is Honest About Its Position

The Benchmark That Actually Matters

The Full Comparison

Medal Count Across 12 Dimensions

On the Collaboration That Produced This Conclusion

The Practical Recommendation

Rust Decorators for Go Developers

#[derive(...)] — Automatic Trait Implementation

#[arg(...)] — Clap CLI Argument Declaration

Writing a Timing Middleware Using `from_fn`

Rust Pattern: `tokio::sync::mpsc` + `select!`

Shared State: From Closures to `AppState`

Rust + Axum: The `IntoResponse` Error Type

When to Use `from_fn` vs Implementing `Layer` Manually

Go Implementation of `sensors/dht22.go`

Rust Implementation of `sensors.rs`

C Implementation of `sensors.c`

`main.go` Implementation

`main.c` Implementation

`main.rs` Implementation

`display/oled.go` Implementation

`display.h`| `display.c` Implementation

`display.rs` Implementation

Go `alarm/alarm.go` Implementation

C `alarm.h` | `alarm.c` Implementation

Rust `alarm.rs` Implementation

Go `wifi/wifi.go` Implementation

C `wifi.h` | `wifi.c` Implementation

Rust `wifi.rs` Implementation

Go `http/server.go` Implementation

C `http.h` | `http.c` Implementation

Rust `http.rs` Implementation

`#[derive(...)]` — Automatic Trait Implementation

`#[arg(...)]` — Clap CLI Argument Declaration

`#[cfg(...)]` — Conditional Compilation

`#[macro_export]` and `#[macro_use]` — Macro Visibility

`#[repr(...)]` — Memory Layout Control

`#[non_exhaustive]` — Future-Proof Enums and Structs

`#[must_use]` — Enforced Return Value Handling

`#[inline]` — Inlining Hints

`#[test]` — Unit Test Declaration

`#[bench]` — Benchmark Declaration

`#[allow(...)]`, `#[warn(...)]`, `#[deny(...)]`, `#[forbid(...)]` — Lint Control

`#[deprecated]` — Deprecation Notices

`#[serde(...)]` — Serialization and Deserialization Attributes