DEV Community: Andrei Merlescu

Sovereign Lemmings Released

Andrei Merlescu — Thu, 23 Jul 2026 03:17:42 +0000

On April 16th, 2026, I published the source code and article called Lemmings Just Spawned on my dev.to profile and my github.com profile. This is the continuation of that effort.

I just did a deep dive into a 2024 Go product that I built called topobuilder in my previous post, and today I am pleased to announce the Sovereign package on Github. It deploys Lemmings to the public cloud in order for you to conduct distributed load testing on your endpoint. The advantage to using Lemmings over tools like NBomber or Apache Benchmarking Tool ab is that each test conducted is session based with a state attached to an NPC or a lemming. The objective of the test is to ensure that n-Lemmings can successfully reach your service within the acceptable period of connection time. I've engineered load testing in these various technologies, including codesenberg's bombardier - none of them measure up to what I built Lemmings to be.

I've seen this before, so I know how to help with it - but before you spend $50,000 on a television ad driving people to your web service, run Lemmings and Sovereign first - make sure your infrastructure is properly configured and working before you send your customers to your service.

The software is 100% free and does not require my involvement at all. I wrote extensive documentation for you. If you need help getting Sovereign Lemmings working, feel free to engage in consulting services.

Enjoy using it!

Now, would you please...
🙌🏻 ASK ME ANYTHING 🙇🏻
👇🏻 about Lemmings Sovereign or Topobuilder

Topobuilder brings a cPanel website into an AWS multi-region containerized application with an HAProxy load balancer

Andrei Merlescu — Thu, 23 Jul 2026 02:31:09 +0000

In 2024, I built a piece of software called topobuilder in Go. I've referenced it in interviews often enough that it deserves a public page to point at — so here's what it is and how I built it, told through fragments of a closed-source codebase.

What Is Topobuilder?

topobuilder is a go binary that runs off a single YAML configuration file that defines an existing PHP website hosted on a cPanel server. The defaults assume that any database connectivity is going to be performed over RDS or another remote connection. What you're doing is going from a single region into a multi-region load balanced containerized application. It takes about 12-36 minutes to deploy a 3-6-9 region cluster with an HAProxy load balancer. 3 regions is 12 minutes; 9 regions defaults to 36 minutes but can also be 12 minutes by adjusting the configuration — though this increases concurrency load and may result in rate limiting from the API utility.

The binary itself is portable — I've run it from DigitalOcean droplets and OVH boxes as easily as from a laptop. What it provisions is AWS. Where topobuilder runs and what topobuilder builds are two separate questions, and the first one is wide open.

Go Application Design

What I am going to do is explain this program, how it was built, and give you some insights into Go application design. To begin, we have the main.go file that is the primary entry point for the main() func.

package main

import (
    "context"
    "flag"
    "fmt"
    "gopkg.in/yaml.v3"
    "log"
    "os"
    "path/filepath"
    "strings"
    "topobuilder/cmd/models"
    "topobuilder/cmd/verbose"
)

const VERSION = "1.0.0"

var (
    runMode     string
    statePath   string
    configFile  string
    showVersion bool
)

func main() {
    flag.BoolVar(&showVersion, "v", false, "show version")
    flag.BoolVar(&showVersion, "version", showVersion, "show version")
    flag.StringVar(&configFile, "config", filepath.Join(".", "cfg.default.yaml"), "Path to cfg.slug-name.yaml")
    flag.StringVar(&verbose.LogDir, "logs", filepath.Join(".", "logs"), "Path to store verbose logs")
    flag.StringVar(&runMode, "mode", ModeDevelopment, "Runtime mode - choices are: "+strings.Join(RunModes(), ", "))
    flag.StringVar(&statePath, "state", "", "Path to state file")
    flag.Parse()

    if showVersion {
        fmt.Println(VERSION)
        os.Exit(0)
    }

    log.Printf("Topobuilder running with: %s %s", runMode, configFile)

    vLogErr := verbose.InitVerboseLogger()
    if vLogErr != nil {
        log.Fatal(vLogErr)
    }

    ctx := context.Background()
    app := models.NewApplication(ctx, runMode, statePath)
    if err := app.LoadConfigs(configFile); err != nil {
        log.Fatal(err)
    }

    app.Run()

    if cleanErr := app.Cleanup(); cleanErr != nil {
        _, _ = fmt.Fprintln(os.Stderr, cleanErr)
        os.Exit(1)
    }

    // exit
    os.Exit(0)
}

That's topobuilder! 😏🤫 Well, let's actually digest it. Given that I've built configurable that became figtree, why would I use the stdlib flag package for topobuilder? Because this application doesn't need to dynamically interact with the configuration runtime the way a web server needs to reload its SSL certificates across rotations without forcing the binary to be restarted. In topobuilder, we read our configs and then begin processing the application. Right tool, right job.

We'll break each of these down further, but I use the models package to return a new app that I can use. This is the primary entrypoint for topobuilder.

app := models.NewApplication(ctx, runMode, statePath)

Once we have an app, we need to load the massive YAML config file into the runtime. Instead of getting into what the configurations are for topobuilder, I am going to focus on how the .LoadConfigs(path string) operates in the (app *Application) itself.

if err := app.LoadConfigs(configFile); err != nil {
    log.Fatal(err)
}

Once the configurations are loaded, the bulk of the application's processing is actually conducted in this one line:

app.Run()

If the .Run() has a problem, it'll be captured in the .Cleanup() method in the (app *Application) definition.

if cleanErr := app.Cleanup(); cleanErr != nil {
    _, _ = fmt.Fprintln(os.Stderr, cleanErr)
    os.Exit(1)
}

Now, before we get into the configuration of topobuilder, we need to discuss the verbose package first.

The `verbose` package

Extracted into its own package, verbose provides a logger capable of scrubbing secrets before they touch STDOUT while preserving the written values to disk in your actual log file.

go get -u github.com/andreimerlescu/verbose

With the verbose package, you interact with it using .AddSecret(), .RemoveSecret(), .ImportSecrets(), and .AddKeyType() when handling sensitive data that you want to suppress from STDOUT, but not from the written log file.

// Existing SHA512 HEX strings + length can be registered below
verbose.ImportSecrets(map[string]int{
    "abc123...sha512hex...": 32,
})

// New header+trailer pattern to filter between values out of logs
verbose.AddKeyType(verbose.KeyType{
    Opening: "BEGIN_MY_SECRET",
    Closing: "END_MY_SECRET",
})

// Add a secret to `verbose` filtering
verbose.AddSecret(verbose.SecretBytes("my-api-token"), "[REDACTED]")

// Remove a secret from `verbose` filtering
verbose.RemoveSecret(verbose.SecretBytes("my-api-token"))

// render a stack trace to return with
verbose.TracefReturn("invalid -name provided: %v", *name)

// bypass sanitization — prints the raw value to the verbose log
verbose.Plain("The raw value is:", *secret)

// this will redact the secret automatically
verbose.Printf("Hello %s, your secret is safe: %s", *name, *secret)

With the verbose package, you're able to safely register new secrets at runtime and then rely on verbose.Printf(string, any) and verbose.Plain(any), plus many other fmt-style methods including verbose.TracefReturn(any), verbose.Sanitize(any), and verbose.Scrub(any). Throughout the application, topobuilder writes things that could contain secrets to STDOUT, but uses the verbose package to ensure that *** and [REDACTED] are what actually appear. This made running a demo in front of stakeholders not a zero-day incident waiting to happen. When I needed the actual values, I could open the text file written to disk and retrieve the raw value that way, or rely on the verbose.Plain(any) method.

flag.StringVar(&verbose.LogDir, "logs", filepath.Join(".", "logs"), "Path to store verbose logs")

In the main() func in the main.go file, you can see that we are directly assigning via the flag.StringVar method a value directly into the &verbose.LogDir string with a default of ./logs (OS safe). This means that -logs /var/log/myApp sets verbose.LogDir = /var/log/myApp and it's scoped package-wide regardless of where or what calls verbose.*.

The `models` package

This is where the magic happens and where we'll spend the most time digging in for your learning curiosity.

func (app *Application) LoadConfigs(configFile string) (err error) {
    // validate config file
    if len(configFile) == 0 {
        log.Fatal("invalid -config value provided")
    }
    configFileBytes, readErr := os.ReadFile(configFile)
    if readErr != nil {
        log.Fatal(readErr)
    }
    if err = yaml.Unmarshal(configFileBytes, app.config); err != nil {
        log.Fatal(err)
    }
    verbose.Asis("VERIFYING APPLICATION RUNTIME")
    startedAt := time.Now().Local()

    if err = app.config.Validate(app); err != nil {
        log.Fatal(err)
    }

    verbose.Asf("APPLICATION RUNTIME VERIFIED (took %d seconds)!", int64(time.Since(startedAt).Seconds()))
    return
}

This method is small despite doing so much. The -config path is read into topobuilder, pointing at a YAML file containing your runtime configurations. Every failure here is fatal by design — this is the gate, nothing has been provisioned yet, and a half-validated config should never reach Run(). Failing loudly at the door is cheaper than failing quietly in region seven.

You'll also see another method from the verbose package here — .Asis(any) does as it says, printing the value as it is, meaning no filtering takes place. Static strings like VERIFYING APPLICATION RUNTIME are informational notices that contain no secrets and therefore shouldn't use verbose.Printf — otherwise you're spending cycles filtering nothing.

The true magic is happening here:

app.config.Validate(app)

In order to understand what this line is doing — and why it can take up to 6 minutes to complete depending on topology size — let's look under the hood. Shall we?

Let's begin with what Application is, so we can see what app.config is talking about.

type Application struct {
    ctx       context.Context
    mode      ModeType
    config    *Config
    state     *TBState
    stateFile string
    user      *user.User
}

We have a *user.User stored as app.user that can be nil, and a state + stateFile used for a topobuilder state file. The mode was defined from main() above and the ctx is passed in from context.Background() in main() as well.

The Config struct is where the rules of engagement live for the YAML Configuration File that topobuilder accepts as the -config value.

type Config struct {

    // Required Properties

    Name            ProjNameKey   `json:"name" yaml:"Name"`
    Slug            ProjSlugKey   `json:"slug" yaml:"Slug"`
    Domain          ProjDomainKey `json:"domain" yaml:"Domain"`
    Mode            ModeType      `json:"mode" yaml:"Mode"`
    Email           string        `json:"email" yaml:"Email"`
    RollbackEnabled bool          `json:"rollback_enabled" yaml:"RollbackEnabled"`

    // Optional Properties

    Firewall     FirewallConfigs     `json:"firewall" yaml:"Firewall"`
    Directories  DirectoriesConfigs  `json:"directories,omitempty" yaml:"Directories,omitempty"`
    OnePassword  OPConfigs           `json:"one_password,omitempty" yaml:"OnePassword,omitempty"`
    AWS          AWSConfigs          `json:"aws,omitempty" yaml:"AWS,omitempty"`
    GitLab       GitLabConfigs       `json:"gitlab,omitempty" yaml:"GitLab,omitempty"`
    EBS          EBSConfigs          `json:"ebs,omitempty" yaml:"EBS,omitempty"`
    Ports        PortsConfigs        `json:"ports,omitempty" yaml:"Ports,omitempty"`
    LoadBalancer LoadBalancerConfigs `json:"load_balancer,omitempty" yaml:"LoadBalancer,omitempty"`
    SSL          SSLConfigs          `json:"ssl,omitempty" yaml:"SSL,omitempty"`
    Docker       DockerConfigs       `json:"docker,omitempty" yaml:"Docker,omitempty"`
    SSHConfigs   SSHConfigs          `json:"ssh,omitempty" yaml:"SSH,omitempty"`
    Wazuh        WazuhConfigs        `json:"wazuh,omitempty" yaml:"Wazuh,omitempty"`
    Secrets      SecretsConfigs      `json:"secrets,omitempty" yaml:"Secrets,omitempty"`
    Times        TimesConfig         `json:"times,omitempty" yaml:"Times,omitempty"`
    ShellKeys    ShellKeys
}

The Config struct is split into two groups of properties, arbitrarily separated by a comment only, for required and optional. The required properties are flattened types. The optional properties are additional struct {} definitions with their own rules. Ultimately, what this flattened Config struct {} offers is a YAML Configuration that natively looks something like this:

---
Name: My Landing Site
Slug: landing-1
Domain: mylandingsite.com
Mode: Development
Email: info@mylandingsite.com
RollbackEnabled: true

Firewall: # properties defined in the FirewallConfigs struct
Directories: # properties defined in the DirectoriesConfigs struct
OnePassword: # properties defined in the OPConfigs struct
AWS: # properties defined in the AWSConfigs struct
GitLab: # properties defined in the GitLabConfigs struct
EBS: # properties defined in the EBSConfigs struct
Ports: # properties defined in the PortsConfigs struct
LoadBalancer: # properties defined in the LoadBalancerConfigs struct
SSL: # properties defined in the SSLConfigs struct
Docker: # properties defined in the DockerConfigs struct
SSH: # properties defined in the SSHConfigs struct
Wazuh: # properties defined in the WazuhConfigs struct
Secrets: # properties defined in the SecretsConfigs struct
Times: # properties defined in the TimesConfigs struct

The pattern is that a <Property>: at the root level of the YAML Configuration File is defined as type <Property>Configs struct {} in the Go program — as you see above. So when adding Something: it would have a type SomethingConfigs struct {} attached to it, defined as YAML using camel-case and JSON using underline_connected_words.

Lines 48-219 of the config.go file are dedicated just to the implementation of app.config.Validate(app), expecting back an error or nil.

First the function handles — without revealing the whole thing — the required properties in series.

errs = data.AppendError(errs, cfg.Name.Validate(app))

data.AppendError is a helper from the data package (similar in spirit to verbose) that performs data manipulation tasks like appending an error type, unlike the bare append(slice, value) pattern.

cfg.Name points to the Name property in the Config struct. That is a type ProjNameKey which has defined:

func (n ProjNameKey) Validate(app *Application) error {}

In fact — this pattern is used on every property defined in the Config struct, both optional and required. What Validate(*Application) is doing behind the scenes is calling .Validate(*Application) on each element in the Config{} itself. That means WazuhConfigs.Validate(*Application) is defined and returns an error type, and so does everything else in there.

The next part of the configuration loading is done in a concurrent-where-possible manner that assumes and understands that some tasks take longer than others. This is why I use conditional mutexes as coordinators:

awsCoordinator := sync.NewCond(&sync.Mutex{})
dockerCoordinator := sync.NewCond(&sync.Mutex{})
deploymentCoordinator := sync.NewCond(&sync.Mutex{})

Lines 144-159 show us:

// Validate AWS Configs
// awsCoordinator issues Wait signal (blocks this goroutine)
// dockerCoordinator issues Broadcast signal
go func(wg *sync.WaitGroup, errCh chan<- error) {
    defer func() {
        dockerCoordinator.L.Lock()
        dockerCoordinator.Broadcast() // notify all waiting
        dockerCoordinator.L.Unlock()
        wg.Done()
    }()
    awsCoordinator.L.Lock()
    awsCoordinator.Wait()
    awsCoordinator.L.Unlock()
    errCh <- cfg.AWS.Validate(app)
}(&wg, errCh)

What these coordinators encode is a dependency graph, not just raw parallelism. Each validation goroutine waits on the coordinator that gates it, does its work, and broadcasts the next coordinator on the way out via defer. An earlier goroutine broadcasts awsCoordinator when its own prerequisites are satisfied, which releases this one; when AWS validation finishes, its defer broadcasts dockerCoordinator, releasing Docker validation, which eventually chains into deploymentCoordinator. The graph is what makes the ordering real — you can't validate a Docker registry against credentials you haven't resolved yet, and you can't resolve those credentials before 1Password has been reached.

Notice that I am passing a pointer to *Application into the Validate(*Application) method attached to the AWSConfigs struct. Also notice how I'm passing the response from that validation directly into errCh, which is a buffered channel of errors. Everything that can run wide runs wide; everything with a real prerequisite waits its turn.

For each of the optional configurations, the coordinators balance the order of validation operations needed to properly validate the runtime of topobuilder before it deploys anything into the wild.

The AWSConfigs struct looks like:

type AWSConfigs struct {
    AccessKey       string     `json:"access_key,omitempty" yaml:"ACCESS_KEY,omitempty"`
    AccessSecretKey string     `json:"access_secret_key,omitempty" yaml:"ACCESS_SECRET_KEY,omitempty"`
    Zones           []*AWSZone `json:"zones,omitempty" yaml:"Zones,omitempty"`
}

Your YAML Configuration will look like:

AWS:
   AccessKey: ""
   AccessSecretKey: ""
   Zones: # the AWSZone struct

The Zones property in the AWSConfigs struct also follows the .Validate(*Application) pattern in the AWSZone struct itself.

Lines 54-63 of the config_aws.go file contain:

if strings.HasPrefix(aws.AccessSecretKey, `op://`) {
    op, pErr := NewOPParse(app, app.config.AWS.AccessSecretKey)
    if pErr != nil {
        return pErr
    }
    value, err := op.GetValue()
    if err != nil {
        return err
    }
    app.config.AWS.AccessSecretKey = strings.Clone(value)
}

This magical little block allows the YAML to reference 1Password secrets via the op://<Vault>/<Item>/<Field> lookup syntax. If you've also defined the OnePassword: properties in the config file, you can use op:// values and topobuilder will look them up and automatically register the retrieved secrets with the verbose package — meaning a secret becomes redactable the instant it exists in memory, and your config file on disk never held it in the first place. Throughout many parts of the application we pass the *Application pointer directly into struct methods, including NewOPParse, which returns a 1Password structure with a bunch of methods attached including .GetValue().

Lines 69-93 in the same file look like:

// THE SETUP

errCh := make(chan error, len(aws.Zones))
doneCh := make(chan struct{})
wg := new(sync.WaitGroup)
errs := make([]error, 0)

// ZONES PROCESSED IN GOROUTINE -> EACH ZONE = GOROUTINE

go func() {
    for i, zone := range aws.Zones {
        i := i
        wg.Add(1)
        go func(wg *sync.WaitGroup, errCh chan<- error, zone *AWSZone, i int) {
            defer wg.Done()
            errCh <- zone.Validate(app, i)
        }(wg, errCh, zone, i)
    }
    wg.Wait()
    close(errCh)
}()

// COLLECT ERRORS

go func() {
    for err := range errCh {
        errs = data.AppendError(errs, err)
    }
    doneCh <- struct{}{}
    close(doneCh)
}()

// WAIT FOR EVERYTHING

<-doneCh

First we set up the concurrency channels, slices, and wait group; then we proceed to spawning two goroutines. The first is for the zones processing and the second is for the error collecting. Each zone defined is spawned into its own goroutine.

Without the <-doneCh at the end of the block, the zones would never validate. If the configuration calls for three zones, then there will be three spawned goroutines — one for each zone. If a zone yields an error, that value is passed into errCh and then picked up by the error collector via range errCh.

After each of these extensive checks is performed on each of the components used throughout topobuilder, app.config.Validate(app) finally completes!

verbose.Asis("SUCCESSFULLY VALIDATED APPLICATION RUNTIME ENVIRONMENT!")

That brings us back up to main() where we hand off to app.Run() next. Lines 131-194 in application.go, the Run() method is defined as:


// Run iterates over all AWS Zones and deploys the cluster topology to that endpoint
func (app *Application) Run() {
    fmt.Println("Deploying topology...")
    startedAt := time.Now().Local()
    var err error

    // Start a rollback
    rollback := app.NewRollback()

    // create the load balancer
    rollback, err = app.CreateLoadBalancer(rollback)
    if err != nil {
        // TODO #feature-rollback implement rollback here
        log.Fatal(err)
    }

    // build the image
    rollback, err = app.BuildImage(rollback)
    if err != nil {
        log.Fatalf("BuildDockerImage() failed with err: %v", err)
    }

    // create the topology
    var clusters []*Cluster
    rollback, clusters, err = app.BuildTopology(rollback)
    if err != nil {
        // TODO #feature-rollback implement rollback here
        log.Fatal(err)
    }

    // configure the network
    rollback, err = app.ConfigureNetwork(rollback, clusters)
    if err != nil {
        _, _ = fmt.Fprintf(os.Stderr, "NetworkClusters(app, rollback, clusters[%d]) resulted in networkingErr: %v\n",
            len(clusters), err)
    }
    fmt.Printf("Finished establishing multi-cluster network.")

    // configure HAProxy from the clusters
    rollback, err = app.ConfigureLoadBalancer(rollback, clusters)
    if err != nil {
        log.Fatal(err)
    }

    // update the domain's dns to point to the load balancer
    rollback, err = app.PublishLoadBalancer(rollback)
    if err != nil {
        log.Fatal(err)
    }

    state, stateErr := NewTBState(app, rollback, clusters)
    if stateErr != nil {
        log.Fatal(stateErr)
    }

    saveStateErr := state.SaveTo(app.stateFile)
    if saveStateErr != nil {
        log.Fatal(saveStateErr)
    }

    fmt.Printf("Wrote Topobuilder State to %s\n", app.stateFile)

    app.DeploymentSummary(startedAt, clusters)
}

This is where the actual meat and potatoes, so to speak, are contained for the binary. First, I establish a rollback plan. Currently unimplemented, the rollback plan is passed through each of the steps since in the event of a rollback being triggered, that would invoke the block of code in the comment. The scaffolding is threaded everywhere it needs to be — the execution is the next chapter.

When the load balancer is created, a set of .tf files are rendered by topobuilder in the DirectoriesConfigs.TerraformDir property. Then terraform apply is executed in that path until the HAProxy instance is up and running. topobuilder looks at the output of terraform, but it requires further capability verification before it continues — Terraform reporting success and the host being ready to do its job are two different claims, and I only trust the second one.

Next we see that app.BuildImage(rollback) is called. This connects to cPanel and compiles a Docker Image based on the PHP website. The topobuilder binary uses the DirectoriesConfigs struct to define where the Dockerfile is going to be written and the path where various docker commands will be executed. This method can take a long time depending on the size of the application and network conditions. The file produced is a .tar.gz inside the docker workspace directory. It's the image of the container that is going to be deployed on the various endpoints.

During the deployment of the application, Provisioner is a struct used throughout the BuildTopology(rollback) function. The pattern was <Utility>Provisioner for the interface. If the utility was DockerImage, then the provisioner was DockerImageProvisioner.

type DockerProvisioner interface {
    Installable
    Pingable
    Runnable
    Recoverable
    Prune() error
    Reset() error
}

type ProvisionerDocker struct {
    provisioner *Provisioner
}

// NewDockerProvisioner attaches DockerProvisioner to Provisioner
func NewDockerProvisioner(p *Provisioner) DockerProvisioner {
    return &ProvisionerDocker{provisioner: p}
}

// Status returns a DockerStatus populated with data
func (docker *ProvisionerDocker) Status() *DockerStatus {}

// Recover will attempt to get the docker process started on the Server
func (docker *ProvisionerDocker) Recover() error {}

// Start initiates the docker process on the Server
func (docker *ProvisionerDocker) Start() error {}

// Stop will terminate the docker process
func (docker *ProvisionerDocker) Stop() error {}

// Online checks ps aux for docker on each Instances' Server
func (docker *ProvisionerDocker) Online() bool {}

func (docker *ProvisionerDocker) Reset() error {}

// Uninstall removes docker from the Server
func (docker *ProvisionerDocker) Uninstall() error {}

// Installed checks ps aux for docker on each Instances' Server
func (docker *ProvisionerDocker) Installed() bool {}

// Install puts the docker engine on the Instances Server
func (docker *ProvisionerDocker) Install() error {}

// Prune runs docker prune on each Instances Server
func (docker *ProvisionerDocker) Prune() error {}

I define provisioner capabilities using the interfaces as:

type Installable interface {
    Install() error
    Uninstall() error
    Installed() bool
}

type Populatable interface {
    Populatable() PopulatableData
}

type Pingable interface {
    Online() bool
}

type Recoverable interface {
    Runnable
    Pingable
}

type Runnable interface {
    Start() error
    Stop() error
}

type Stateful interface {
    SetState(enabled bool) error
}

This means that I can have n-Provisioners with capabilities like being Stateful, Runnable, Recoverable, Pingable, Populatable, Installable — and have predictable behavior across packages like igo and counter, including docker and the Wazuh Agent, a DevSecOps monitoring capability supported by topobuilder. As each of these provisioners is consumed and used, the output is written via the verbose package where the raw values are written to the log file itself. This provides the operator access to see what each instance is doing as it's happening.

The <Utility>Provisioner interface is defined to consume the capabilities above like:

type DockerContainerProvisioner interface {
    Recoverable
    Installable
    Runnable
    Pingable
}

So you can see that the <Utility>Provisioner interfaces contain contracts for various capabilities like being Recoverable, Installable, Runnable and/or Pingable.

Then the various Provisioner implementation methods are defined against the following struct:

type ProvisionerDockerContainer struct {
    provisioner *Provisioner
}

This pattern is similar — it's Provisioner<Utility> in the struct name, and it has its own methods as the <Utility>Provisioner interface requires. Read one of these and you can predict all of them, which is the whole point of building it this way.

Next, we see app.BuildTopology(rollback) — which executes many of the AWS commands needed to create an EC2 instance and consumes the EBSConfigs struct out of the main config. The disk options on the cluster are cluster-wide and defined in one location.

As the topology is created, each zone runs concurrently (though 3 at a time is a configurable limit) as it creates the EC2 instances, uploads the .tar.gz image file, and installs the necessary provisioned software for the hosts. Once the load balancer can listen on the configured Ports: settings, the AWS networking is secured.

Then we see app.ConfigureNetwork(rollback, clusters). This is where the security groups are configured, the firewalld process, and the connectivity checks take place. This configures port access to and from the instance and the load balancer. This stage ultimately secures the network. A properly configured VPC is required before topobuilder can run.

Then, depending on whether Cloudflare is being used or if HAProxy is being used as the load balancer of choice, the app.ConfigureLoadBalancer(rollback, clusters) block is responsible for either running the necessary Cloudflare API calls, or compiling an haproxy.cfg file that gets loaded into a new EC2 instance created and designated as the load balancer entrypoint. topobuilder establishes secure connectivity between each endpoint and uses encrypted traffic for all data transmissions.

Once the HAProxy load balancer is healthy, then we can run app.PublishLoadBalancer(rollback), which issues a DNS record update to the Cloudflare API to set the Domain: <string> value from the YAML Configuration file defining the website you're deploying the cluster out to. This A record gets updated to the HAProxy instance.

Once the cluster has been created, the docker image deployed and launched, running and healthy, and the load balancer up and serving traffic on all endpoints in a health-check-verified manner, NewTBState(app, rollback, clusters) is invoked next. This writes a new .tbstate JSON structured text file that records the state of the output of the entire deployment step by step, including timestamps of when things were executed. This log of record is maintained during the runtime of topobuilder and is part of the rollback functionality. Once the state of the cluster is compiled, it's saved via state.SaveTo(app.stateFile) before app.DeploymentSummary(startedAt, clusters) is called to render a summary of the deployment to STDOUT.

Why I Built This

Front end landing pages like a basic PHP website that uses an RDS connected database are the perfect contender for topobuilder. It allows for spot instances to be selected in the configuration, and a campaign to be executed for a FRACTION OF THE COST. Ultimately — if you have a large cluster of instances serving thousands of clients, you can do it in the first class cabin for a premium. You might call that Kubernetes or Elastic Container Service (ECS). I built the budget Spirit Airlines alternative. Yes, topobuilder truly is like Spirit Airlines 🤫 — no seat recline, gets you there, costs a quarter as much.

That's also my honest answer when someone asks what do you know about Kubernetes. I know enough to understand the tax associated with its operations, and enough to explain to EVPs and CTOs what each option actually gives them and what it costs. topobuilder was built in a single month and delivered for a major launch. OPEX dropped dramatically because of it. When I interview with your company, I am interviewing you just as much as you are interviewing me — it goes both ways — and this is exactly the kind of tradeoff I want to be talking about in that room.

I'm talking about it now because it was super cool to build. The source stays closed — the use case is narrow enough that releasing it wouldn't serve anyone, and it was built two years ago and has not been updated since. It hasn't needed updating. ❤️‍🔥 For now 😏🤫. But how I built the configuration and the provisioners themselves are the meat and potatoes I'm offering for your reading time this Wednesday in July.

Alongside that, The Library still needs contributions despite being Locked In With AI, and Applicant Tracking Systems continue to do what they've done to the interviewing market. A single topobuilder config file can run a few hundred lines, and its syntax is legible directly from the structs above — which is also why AI-powered documentation systems digest this application so effectively.

Conclusion

I've been writing software for 17 years, since graduating college as a Computer Engineer and running the IEEE Student Branch I joined as a widdle freshman. At Cisco and Oracle, much of my career was closed source and off limits. After the pandemic, I wanted to give selflessly without expecting anything in return. That's why I wrote Project Apario into a three binary trinity called reader, writer and search.

When the problem statement was made by the client that requested topobuilder, I assured them that I have built complex software in Go from start to finish that is stable and shipped into production for months with minimal updates needed for maintenance — and then, with their trust, I built topobuilder over a single month. It combined many years of experience deploying multi-region architectures and all the manual work involved in getting any of those automated systems to actually work. I wanted to build something that could go from start to finish in a way I understood top to bottom. topobuilder was the result.

One number surprised me. When I ran text analysis against the repository, out of roughly 72,000 words of source there were only about 4,800 unique ones — an average of 15 repetitions each. That's not mystery, it's what a small pattern language looks like from the outside: Validate(*Application) on every config type, <Utility>Provisioner for every contract, Provisioner<Utility> for every implementation, the same capability verbs on every host. Once you've seen the pattern three times, you've seen all fifteen instances of it. 🤣

There's plenty I've left out here — how BuildImage turns a live cPanel site into a reproducible image, where the rollback design is headed, how nine regions collapse from 36 minutes to 12. Those are better conversations than paragraphs, and I'm always glad to have them.

The source stays closed. The ideas don't have to be — the config validation pattern and the provisioner capability interfaces are above in full, and they're yours to take. Twelve minutes, one YAML file, three regions, one binary I understand top to bottom.

The Day I Stopped Asking Strangers for My IP

Andrei Merlescu — Wed, 22 Jul 2026 01:34:03 +0000

A Story of Go, systemd, and SELinux Left Enforcing

Let me tell you a story about the day I stopped asking strangers on the internet for my own IP address.

Years ago I did what everybody does. I opened a browser, typed what is my ip into a search bar, clicked the first shiny result, and got my answer. Convenient. Free. Instant. Then one afternoon I happened to have tail -f running on my firewall logs when I did it — and I watched the scans arrive quicker than you can say eenie meenie miney moe. You hit their endpoint, your address lands in their logs, and shortly after, the probes come knocking. That's not paranoia, that's just how the watering hole works.

If you're serious about your infrastructure, that lookup should happen on hardware you control. It's a minimal expense — this whole service idles at about 3 MB of RAM — and it means your address never has to volunteer itself to someone else's access logs just so you can read it back.

The first version of this I ever wrote was in PHP, running behind Apache or Nginx or Caddy depending on the year. It worked. But given that Go has the ability to do so much, why not do more? So that's exactly what I did.

Meet the binary

I'd like to introduce you to a Git repository called ip.ishere.dev. Despite looking like a domain name, it's actually a Go application that compiles into a single self-contained web server for the explicit purpose of displaying your current IPv4 and IPv6 addresses. And when the industry finally blesses us with an IPv8 someday (I'm a patient man 😏), support arrives the moment the net package in Go learns the trick.

Inside that one binary lives a Rate Limiter, a Concurrency Limiter, a CORS Handler, CSP Enforcement, and automatic HTTPS Upgrades. Every request is persisted to a SQLite3 database. No Apache. No Nginx. No reverse proxy babysitter. One process, one port pair, done.

Now, about the machine it lives on. I prefer Rocky 9 Linux when I am deploying services, and I like to have SELinux set to enforcing along with fail2ban and firewalld standing guard. A lot of tutorials would tell you to setenforce 0 right about now. We are not going to do that. That's the whole point of this article.

Step 1 — Acquire it

git clone git@github.com:andreimerlescu/ip.ishere.dev.git 
cd ip.ishere.dev

Once we have it, you'll see that alongside the Go source there are a few files that do not belong to the binary itself:

Makefile
ip.service
run-app.sh

These three are the deployment story. The Makefile offers the ability to run:

make all — Runs everything below...
make mac-intel — Compiles the binary for macOS Intel.
make mac-silicon — Compiles for macOS Silicon.
make linux-arm — Compiles for Linux ARM.
make linux — Compiles for Linux x86.
make clean — Removes compiled binaries from the filesystem.
make test — Runs the test suite against the binary.

Step 2 — Teach systemd about it

I want the full lifecycle vocabulary on this box:

sudo systemctl start ip.service
sudo systemctl stop ip.service
sudo systemctl restart ip.service
sudo systemctl status ip.service

For that, the system needs the ip.service file installed. The contents:

[Unit]
Description=IP IsHere Service
After=network.target

[Service]
Type=simple
User=admin
Group=admin
WorkingDirectory=/home/admin
ExecStart=/home/admin/ip.ishere.dev-linux-amd64
Environment=IP_CONFIG_FILE=/home/admin/app/config.yaml
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target

Before we go one line further, make a decision and commit to it: where does this binary live? The repo ships with /home/admin defaults. My production box prefers /opt/ip.ishere.dev with the binary in /usr/local/bin. Either is fine — but ExecStart, WorkingDirectory, the Environment=IP_CONFIG_FILE line, and the fallback execution line at the bottom of run-app.sh must all tell the same story. Mismatched paths are the number one reason a service like this "mysteriously" won't start, and I'd rather you hear it from me than from journalctl.

Did You Know: goini can do this rewiring for you!

When I'm programmatically deploying these kinds of applications, I wanted a means to embed .ini file interactions directly into my Bash. So I built one. It exits with code 0 on success and 1 on error, which makes it a first-class citizen inside if statements and set -e scripts — exactly the reason it exists.

go install github.com/andreimerlescu/goini@latest

Then you can run:

goini --ini ip.service \
      --section Service \
      --key ExecStart \
      --value "/usr/local/bin/ip.ishere.dev" \
      --modify-key

goini --ini ip.service \
      --section Service \
      --key Environment \
      --value "IP_CONFIG_FILE=/opt/ip.ishere.dev/cfg.yml" \
      --modify-key

goini --ini ip.service \
      --section Service \
      --key WorkingDirectory \
      --value "/opt/ip.ishere.dev" \
      --modify-key

goini --ini ip.service \
      --section Service \
      --key User \
      --value "$(whoami)" \
      --modify-key

goini --ini ip.service \
      --section Service \
      --key Group \
      --value "$(whoami)" \
      --modify-key

Or if you want to manually edit the file using vi or nano or something else, go for it — I think sed is pretty cool and awk can definitely do it too. 😏

Step 3 — run-app.sh, or: how to befriend SELinux instead of shooting it

Once the unit file tells the truth, run-app.sh installs and launches everything. It opens like this:

#!/bin/bash

set -e

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

EXE=$(realpath $(find . -type f -name 'ip.ishere.dev-linux-amd64'))
APP=$(realpath $(find . -type d -name 'app'))
APP_DATA=$(realpath $(find . -type d -name 'app-data'))

service_app="ip.service"
service_file="/etc/systemd/system/${service_app}"

This defines the executable as EXE, the application directory as APP, and the workspace as APP_DATA. Then we name the service_app (the file we just edited with goini) and its destination service_file.

Next comes check_selinux_status, so we can verify what kind of machine we're standing on before we start labeling files:

# Function to check SELinux status
function check_selinux_status() {
    if command -v getenforce >/dev/null 2>&1; then
        local selinux_status=$(getenforce 2>/dev/null || echo "Disabled")
        case "$selinux_status" in
            "Enforcing"|"Permissive")
                return 0  # SELinux is active
                ;;
            "Disabled"|*)
                return 1  # SELinux is disabled or not available
                ;;
        esac
    esac
    else
        return 1  # SELinux tools not available
    fi
}

Notice that both Enforcing and Permissive return 0. That's deliberate. Permissive mode still labels and still logs — it just doesn't block — so we want our contexts in place either way. The function returns 0 or 1 precisely so it can be consumed as if check_selinux_status; then.

Let's make sure the workspace exists:

if ! [ -d "${APP}" ]; then
    mkdir "${APP}"
fi
if ! [ -d "${APP_DATA}" ]; then
    mkdir "${APP_DATA}"
fi

And now the main event:

# Check if SELinux is enabled
if check_selinux_status; then
    echo -e "${GREEN}SELinux is active. Setting up SELinux contexts for ip application...${NC}"

    # Remove any existing file contexts to avoid conflicts
    echo -e "${YELLOW}Cleaning up existing file contexts...${NC}"
    sudo semanage fcontext -d "${APP}(/.*)?" 2>/dev/null || true
    sudo semanage fcontext -d "${APP_DATA}(/.*)?" 2>/dev/null || true
    sudo semanage fcontext -d "${EXE}" 2>/dev/null || true

    # Set file contexts using httpd_sys_content_t
    echo -e "${YELLOW}Setting file contexts...${NC}"
    sudo semanage fcontext -a -t bin_t "${EXE}"
    sudo semanage fcontext -a -t httpd_sys_content_t "${APP}(/.*)?"
    sudo semanage fcontext -a -t httpd_sys_rw_content_t "${APP_DATA}(/.*)?"

    # Apply the contexts
    echo -e "${YELLOW}Applying file contexts...${NC}"
    sudo restorecon -v "${EXE}"
    sudo restorecon -Rv "${APP}"
    sudo restorecon -Rv "${APP_DATA}"

    echo -e "${GREEN}SELinux context setup complete!${NC}"
else
    echo -e "${YELLOW}SELinux is disabled or not available. Skipping SELinux context setup.${NC}"
fi

In the above block we're running semanage to declare the labels our resources should carry, and then applying them with restorecon. The -e on the echo allows the color output through ${GREEN}, ${YELLOW}, and ${NC}.

The sermon

I want to break down the SELinux stuff for you plainly, because this is where most people bail.

I have watched brilliant engineers — including folks at studios protecting billions in assets — reach for setenforce 0 the moment an AVC denial appears in their logs. They're not lazy; they're tired. SELinux answers questions nobody remembers asking, and the denials feel like the system fighting you. So they disable the guard because the guard asked a question. We don't do that here.

The mental model is simple: every file wears a name tag, and every process only trusts certain name tags. Your job when enforcing is on is not to argue with the doorman — it's to hand out the right name tags, deliberately, one binary at a time.

Execution via bin_t — this tag says "I am a legitimate executable":

# bin_t permits binary execution
sudo semanage fcontext -a \ # apply
                       -t bin_t \ # context to
                       "${EXE}" # path

Since this application services web traffic on ports like :443 and :80 (customizable), we reuse the well-worn httpd_sys_* family of contexts for the paths it touches — the same tags the OS already understands to mean "web content lives here."

Read-Only access via httpd_sys_content_t:

# httpd_sys_content_t permits read access to path
sudo semanage fcontext -a \ # apply
                       -t httpd_sys_content_t \ # context to
                       "${APP}(/.*)?" # path

Read-Write access via httpd_sys_rw_content_t — this is where the SQLite3 database breathes:

# httpd_sys_rw_content_t permits write access to path
sudo semanage fcontext -a \ # apply
                       -t httpd_sys_rw_content_t \ # context to
                       "${APP_DATA}(/.*)?" # path

Declare, then apply with restorecon. That's the whole ritual. No policy modules to compile, no enforcing disabled, no shame.

Low ports without root

One more gate: ports below 1024 are privileged on Linux. The old answer was "run it as root," which is a terrible trade — all of root's power for one tiny permission. The better answer is setcap, which grants exactly one capability and nothing else:

# Set capabilities for the binary (this works regardless of SELinux status)
echo -e "${YELLOW}Setting capabilities for ip binary...${NC}"
sudo setcap cap_net_bind_service=+ep "${EXE}"

echo -e "${YELLOW}Starting application...${NC}"

Now the admin user's binary can bind :80 and :443, and none of root's other privileges came along for the ride.

Step 4 — Let systemd take the wheel

Next we need check_systemd_service, which ensures the ip.service file is installed where systemd can see it, that systemctl exists, and that the daemon reload succeeds. Same return 0 / return 1 pattern as before:

check_systemd_service() {

    # Check if service file exists
    if [[ ! -f "$service_file" ]]; then
        if [[ -f ip.service ]]; then
            sudo cp "${service\_app}" "${service_file}"
        else
            echo -e "${YELLOW}${service_app} not found at $service\_file${NC}"
            return 1
        fi
    fi

    # Check if systemctl is available
    if ! command -v systemctl >/dev/null 2>&1; then
        echo -e "${YELLOW}systemctl command not available${NC}"
        return 1
    fi

    # Try to reload systemd daemon
    if ! sudo systemctl daemon-reload 2>/dev/null; then
        echo -e "${YELLOW}Failed to reload systemd daemon${NC}"
        return 1
    fi

    return 0
}

Now we consume it. Once systemd is happy, the service is started, enabled, and its status printed to STDOUT. Enabled means: when your machine reboots at 3 AM, this binary comes back without you.

# Try to use systemd service first
if check_systemd_service; then
    echo -e "${GREEN}Found ${service\_app}. Starting via systemd...${NC}"

    # Start the service
    if sudo systemctl start "${service_app}"; then
        echo -e "${GREEN}Service ${service\_app} started successfully${NC}"

        # Enable the service for auto-start
        if sudo systemctl enable "${service_app}"; then
            echo -e "${GREEN}Service ${service\_app} enabled for auto-start${NC}"
        else
            echo -e "${YELLOW}Warning: Failed to enable service for auto-start${NC}"
        fi

        # Show service status
        echo -e "${GREEN}Service status:${NC}"
        sudo systemctl status "${service_app}" --no-pager
    else
        echo -e "${RED}Failed to start service via systemd. Falling back to direct execution...${NC}"
        # Fallback to direct execution
        IP_CONFIG_FILE=/opt/ip.ishere.dev/cfg.yml "${EXE}"
    fi
else
    echo -e "${YELLOW}Using direct execution method...${NC}"
    # Fallback to direct execution
    IP_CONFIG_FILE=/opt/ip.ishere.dev/cfg.yml "${EXE}"
fi

Of course, you don't actually have to write run-app.sh — it ships with the repository. The one line you must review is that fallback execution appearing in both the if and else branches:

IP_CONFIG_FILE=/opt/ip.ishere.dev/cfg.yml "${EXE}"

Point IP_CONFIG_FILE at your config path from Step 2. If systemd ever fails and the fallback fires with a path that doesn't exist on your box, you'll see an error — and now you know exactly why. 🤫 No more mystery.

Step 5 — The config file

But Andrei! What is inside /opt/ip.ishere.dev/cfg.yml? What a wonderful question you ask!

domain: ip.ishere.dev
http: 80
https: 443
key: key.pem
cert: cert.pem
database: /home/admin/app-data/ip_requests.db
connections: 369
advanced: true

(And yes — connections: 369. Tesla knew things.)

There are 42 additional configurables available for your consideration — the answer to life, the universe, and your config file. Some include enable_csp: true, enable_cors: true, enable_prometheus: true, enable_health: true, and enable_stats: true for route protections and observability into your binary. You can customize the endpoints themselves with endpoint_health: "/health", endpoint_stats: "/stats", endpoint_read: "/read", and endpoint_metrics: "/metrics".

Step 6 — Light it up

Once you have this all tied up, run the script and you should see:

[admin@ip ~]$ ./run-app.sh 
SELinux is active. Setting up SELinux contexts for ip application...
Cleaning up existing file contexts...
Setting file contexts...
Applying file contexts...
SELinux context setup complete!
Setting capabilities for ip binary...
Starting application...
Found ip.service. Starting via systemd...
Service ip.service started successfully
Service ip.service enabled for auto-start
Service status:
● ip.service - IP IsHere Service
     Loaded: loaded (/etc/systemd/system/ip.service; enabled; preset: disabled)
     Active: active (running) since Sat 2025-07-12 13:23:39 UTC; 226ms ago
   Main PID: 4856 (ip.ishere.dev-l)
      Tasks: 6 (limit: 4424)
     Memory: 2.9M
        CPU: 8ms
     CGroup: /system.slice/ip.service
             └─4856 /home/admin/ip.ishere.dev-linux-amd64

Jul 12 13:23:39 ip.ishere.dev systemd[1]: Started IP IsHere Service.
Jul 12 13:23:39 ip.ishere.dev ip.ishere.dev-linux-amd64[4856]: 2025/07/12 13:23:39 Starting HT…443
Jul 12 13:23:39 ip.ishere.dev ip.ishere.dev-linux-amd64[4856]: 2025/07/12 13:23:39 Starting HT…:80
Hint: Some lines were hidden, use -l to show in full.

2.9 MB of memory. 8 ms of CPU. SELinux still enforcing. That's the mark.

Now hit the endpoint you defined as domain: in the config:

curl -s -L https://ip.ishere.dev

IPv4: 17.17.17.17
IPv6:

Pipe it like a proper Unix citizen:

curl -sL https://ip.ishere.dev | grep IPv4 | awk '{print $2}'

17.17.17.17

Or take it as JSON:

curl -s -L https://ip.ishere.dev/read.json | jq -r '.ipv4'

17.17.17.17

Why this matters beyond your homelab

Here's the enterprise story hiding inside this little binary. Stand it up on your internal network, point your internal DNS at it — imagine an ip.cisco.com that resolves inside the walls — and voilà: any machine in the fleet can ask for its own 10.x.x.x address plus its WAN, which tells you exactly which root-level gateway that machine egressed through. When you're juggling cloud resources across closed networks, that answer, obtained without touching a public endpoint, is worth its weight.

And if you've used services like What's My IP? before — you already know why keeping this lookup in-house keeps your instances free from the instant scans that follow.

Conclusion

I had an old version of this written in PHP that ran behind Apache or Nginx or Caddy — but given that Go can do so much, why not do more? One binary now carries the rate limiting, the concurrency limits, CORS, CSP, HTTPS upgrades, and SQLite persistence that used to take a whole stack.

Best part: it's entirely free and open source, including the SELinux context installation and the systemd service for Rocky 9 Linux. This binary is one of many in my open source collection, an ecosystem I document in public — production-quality binaries following strong security practices, written down for myself and for you.

I welcome security audits of the binary, testing, and expansion of its functionality.

So tell me: is your fleet running SELinux enforcing, or has somebody quietly setenforce 0'd it when you weren't looking? Drop it in the comments — I'll respond to every single one.

Five Hours Of Interviewing - Zero Questions About The Job

Andrei Merlescu — Fri, 17 Jul 2026 19:26:46 +0000

This spring I interviewed with a company whose product I genuinely respect — an internet-intelligence platform built on DNS data, the kind of quiet infrastructure that keeps the modern web navigable. The role was Senior Distributed Systems Engineer. The mission: help rewrite a core product from C into Rust and Go.

I have lived this exact migration before. I was the Senior Release Manager who oversaw the release process while Dyn's C and Python codebase — an internet-intelligence product of the same species — was rewritten in Go inside Oracle after the acquisition, as that organization scaled from a few hundred engineers into what the world now knows as OCI. I reviewed the pull requests. I signed off on the code that moved from dev to prod. I watched release success climb from roughly 80% to over 99.9% — not because anyone got smarter overnight, but because the process got honest. I have never needed to be the smartest person in the room. My job, for seventeen years, has been building rooms where that stops mattering. Ransomware recoveries at 6 AM. A hundred-plus public repositories. An open-source, three-binary full-text search engine written from scratch.

I spent nearly five hours across this company's interview loop.

Not one question was about distributed systems.

The technical evaluation that decided my candidacy was a grid puzzle: given a matrix of 1s and 0s, count the islands. A freshman flood-fill exercise. In 2026, any AI assistant one-shots it in any language you name, and every candidate knows it, and every interviewer knows every candidate knows it.

I'm not writing this to relitigate my rejection. Rejection is part of the profession. I'm writing because the process itself is the story — and because I kept the timestamps. I'll show them to you before we're done. The process is not unique to one company. It is the industry default, and it is quietly broken at both ends.

The pipeline that optimizes for a human who doesn't exist

Start at the top of the funnel. Applicant Tracking Systems were sold to companies as a solution to volume: too many resumes, not enough recruiter hours. Fine. But an ATS doesn't evaluate people; it evaluates documents against an idealized keyword profile — a phantom candidate assembled from a job description that was itself probably written by committee, or lately, by AI.

Here is the joke the industry hasn't laughed at yet: the only applicants who match that phantom perfectly are the synthetic ones. AI-generated candidates tune their resumes to the keyword spec better than any honest human can, because they are keyword specs wearing a trench coat. So companies now run identity theater to compensate. In my loop, I was asked to disable background blur, hold three fingers in front of my face, and show government ID on camera — before a single technical word was exchanged.

I want you to see one of those moments up close. On a call with a product leader — a genuinely pleasant one — I opened the way the process now requires: ID raised to the lens, the compelled declaration spoken onto the record. I'm not AI. His reply was warm and immediate: "I like the joke. It's always fun. It's a good icebreaker."

Sit with the word always. On the administering side of the table, the humanity-proof has become a recurring bit — reliable light entertainment before the agenda. The ritual's weight is visible only to the party under orders to perform it. Minutes later, the same leader apologized that back-to-back meetings had kept him from reading my resume — and what the system had shown him, it had scrambled, reordering my recent roles, so I spent the opening of my own evaluation correcting the machine's version of my career. Hold those three facts in one hand: I was required to prove I was human. The proof was received as comedy. And neither the machine nor the human across from me knew who I was. The machine misread me, the human hadn't read me, and I was the one under suspicion of being synthetic.

The recruiter, to her credit, was candid: the tooling was surfacing candidates who weren't real, and it was making her job harder. Sit with that too — the company's own operator, complaining to a candidate, mid-screen, about the software standing between them. The ATS was bought as a bot filter and has matured into a bot amplifier, and the cost is paid in friction by exactly the people it was supposed to find.

Counting islands in the age of AI

Now the middle of the funnel: the puzzle.

I understand what these questions used to be for. Twenty years ago, watching someone traverse a grid told you something, because writing code from a blank page was the scarce skill. It isn't anymore. AI has commoditized exactly the layer these puzzles test — clean-room implementation of well-known algorithms under time pressure. Asking flood fill in 2026 is like evaluating a structural engineer by hand-multiplying four-digit numbers with a calculator visible on the table that they're forbidden to touch.

Strip the puzzle down and three signals remain: memorization of textbook material, speed-reading of deliberately tricky problem statements, and willingness to perform a ritual both parties know is disconnected from the job. The first is obsolete. The second, I'll come back to. The third is the quiet one — it selects for compliance, for candidates who will nod along with "we know this doesn't really measure anything" and do it anyway. If you are hiring senior engineers to tell you hard truths about a legacy C codebase, screening for nod-along screens out the trait you need most. Teams that nod along are the teams that are fully offline at 6 AM when the ransomware note arrives.

I know, because I've been the phone call that gets made — and here the story stops being hypothetical. Midway through this loop, unprompted, I handed the interview the incident walkthrough it never requested. Last December: a zero-day, a ransomware note, a fintech's entire cloud footprint dark — roughly a million and a half a year in infrastructure, offline. My phone rang at 6 AM. Before the CTO's. Before the AWS-certified senior engineer's. Mine. I brought them back with seven hours of data loss and no ransom paid, then spent weeks in daily sessions with the CTO converting the recovery into policy — scripts he could run without me, a disaster-recovery plan that became company standard. Composure, ownership, verification, aftermath: the exact evidence a senior systems loop exists to extract, volunteered free of charge, threads dangling everywhere, begging to be pulled.

The response, verbatim: "Okay, cool. Awesome. We're at the fifteen-minute mark."

That is the finding underneath the finding. The loop didn't merely fail to ask good questions. It could not receive good answers. Curiosity had no field in the form. Meanwhile, the questions that would have produced real signal sat unasked: where do you draw the FFI boundary during the transition? Which components earn Rust's ownership model and which are fine as Go services? How do you strangle a monolith serving live DNS traffic without an availability dip? What did the Dyn-to-OCI rewrite get wrong? I would have paid to be asked. I offered to walk through my public repositories — diffs going back years, written before AI existed to write them for me. Instead, an interviewer told me they couldn't tell whether I could write code at all. Nobody had looked. The evidence was one click away, and the process had no slot for it.

The AI double standard

Here is the disconnect that should bother you even if nothing else in this piece does.

AI screened my resume in. An automated agent scheduled and corresponded with me. AI-generated fake candidates forced the identity checks I underwent. And in five hours, the only time a human being discussed AI with me was the moment I was compelled to deny being one — a denial the man across the table called his favorite recurring icebreaker. Then, in the interview room, AI was forbidden: no documentation, no tools, no assistant. A surveilled camera, a clock, and a trick question — a working environment that has not existed since 2022 and will never exist on this job.

I don't use AI to think for me. I use it the way my generation used a datasheet: when I built embedded systems in C, nobody considered it cheating to look up pin specifications, and nobody considered a differential-equations reference a character flaw while assembling a circuit. A professional who hits an unknown looks it up, then interrogates the answer until the why is understood. That interrogation — solution back to problem — is the actual engineering. An interview that bans the tools of the job measures a job that doesn't exist.

And the identity theater carries a deeper absurdity: I had already handed the loop the one humanity proof no synthetic candidate can fake — a 6 AM recovery with named executives who will take your call. The pipeline verified my pulse and discarded my life. For an internet-intelligence company, that should sting. The modern web crawls with agentic traffic — bots with crypto wallets paying their own way into your data, no fingerprint, no fatigue. A hiring pipeline that can't distinguish synthetic candidates from real ones is a small preview of the product problem. Quarantining AI in HR software instead of treating it as core competency is describing your own blind spot out loud.

Who the format filters out

Now the part I have standing to say that most critics of interview culture don't.

English is my second language. I came to America from a Romanian orphanage. And here is a sentence that took longer to write than any code I've shipped: I am a disabled engineer. For decades I refused that word. Where I began — inside Ceaușescu's institutions — disability was not a protected status; it was a sorting mechanism, and being sorted was dangerous. So I ran a dishonest process on myself for most of my career: no incident reviews permitted, no postmortems on the one system I lived inside. Accepting the word was the hardest blameless postmortem I ever convened — decades late, one attendee, the person who signs the release notes.

I disclose this for one reason: so you read the next sentences correctly. The flood-fill puzzle is not beneath me. Under a clock, on camera, in adversarial prose in a language I learned second, it is aimed at me — at precisely the dimensions I finally stopped denying, none of which are the job. Trick-question formats are a tax on second-language readers and on plenty of disabilities that have nothing to do with engineering ability. The codebase does not word its bugs deceptively on purpose. Production incidents do not grade you on reading comprehension in your second language.

Let me be precise, because precision matters: I am not accusing anyone of designing these loops to exclude people like me. I don't believe they were designed at all — that's the problem. They were adopted, unexamined, from a template written for a different era and a different candidate. But a filter doesn't need intent to have a slant. If your loop systematically taxes dimensions orthogonal to job performance — language, processing style, performance under surveillance — you are shrinking your talent pool along lines you never chose and can't defend. That's not a values statement. That's a yield problem, and in some jurisdictions a legal-review problem too.

What a senior loop should look like

Criticism is cheap, so here's the alternative, concretely, for a role like this one.

Review the candidate's actual work first: if they have a decade of public code, spend thirty minutes in it and make them defend their own decisions — nothing exposes a faker faster than their own repository. Run the design session on your real problem — the migration you're hiring for — and grade the trade-off reasoning, not the syntax. Do an incident walkthrough: tell me about a 6 AM page you owned end to end, and pull the thread. If a candidate volunteers one unprompted, that isn't filler before your next agenda item; that's the interview arriving early. Pair on a small, real task with every tool the job allows, AI included, and watch how they verify what the tools produce — that verification instinct is the senior skill of this decade. Treat references as evidence, not paperwork: if executives put their names behind a candidate, read what they wrote before your software replies for you. And when it's over, whatever the outcome: give the human a reason. Five hours of their life is worth one paragraph of yours.

None of this is exotic. All of it produces more signal per hour than flood fill. The puzzle's only advantage is that it's easier to administer — and "easier to administer" is how we got the ATS, too. We keep letting the computer make management decisions because the computer is convenient, then act surprised when reqs stay open for months while engineers who've already done the job walk out of the funnel.

The interview goes both ways

Candidates are interviewing you. Your loop is the only demo of your engineering culture we ever see before signing, and I was running my own audit the whole time.

One exhibit: a leader gave me, unprompted and warmly, the culture speech. Home life intrudes on work all the time, he said; we don't have this artificial boundary between real life and work life; as long as people get their work done, no one cares. I believe he meant it as a gift. Now audit the examples that came wrapped with it: meals cooked on camera during calls, meetings not quite compatible with your time zone, an executive online at 2 AM from the other side of the planet — that's just the reality, right? Every example runs opposite to the framing: work intruding on home, narrated as home being welcomed at work. The speech's most honest detail was accidental — the man delivering it mentioned his own home office, where no one ever bugs him. A boundaryless culture is cheapest for whoever already owns a door.

I am a boundary professional. Release management is the boundary between dev and prod, and every reliability number I've ever posted came from adding gates, not dissolving them. In my trade, work-life segmentation has another name: failure-domain isolation. "We don't have this artificial boundary" translates to "we run everything in one blast radius." There are no artificial boundaries — only enforced ones and failed ones. And notice the rhyme the loop had already taught me: it began by ordering my background blur off, dissolving my home's boundary for the company's gaze. I assumed that was the screening software being paranoid. The culture speech clarified it. The blur never comes back on.

Second exhibit, mine. I asked one diagnostic question: what's the budget for an engineer's workstation, and what's the cadence? It sounds like perks. It's a worldview probe — does the company treat engineer compute as capital or as expense? My own bench, built across seven years, once let me stand up an employer's entire 75-microservice platform locally and take their single-region cloud multi-region in thirty days, on a company-issued laptop that could barely hold a video call. Because when I run terraform apply, the whole fail-fix-verify loop happens inside my own blast radius at zero marginal cost; what crosses to the metered cloud is a verified result, not an experiment. Where iteration is metered, verification gets rationed — and rationed verification is the 80% world I was once hired to end. In 2026 the same silicon is also a privacy boundary: it runs frontier-class open models air-gapped, meaning AI-assisted work on a fifteen-year-old proprietary C codebase where not one token leaves the building. I offered the arrangement plainly — company-owned encrypted drive, my compute, the IP boundary explicit — which is, I'd learn on that same call, the identical trust architecture the company pitches its own partners: run our sensors, because you can read every line that touches your data. Their pitch and my offer were the same argument. Neither side noticed, and I own my half of that miss — in the room I argued capacity when I should have said privacy out loud. What I got back was peripherals: pick a laptop, here's a stipend, ask the engineering manager. Compute as comfort. The question was compute as capability.

Last finding, offered in the postmortem spirit because it generalizes past any one company: if you hold a leadership title — director, head-of, VP, earned or inflated, it genuinely does not matter — and the calendar hands you thirty minutes with a candidate whose reference list runs to EVP and CTO, the ante is thirty seconds of curiosity about who's on the other end. Preparation can be a casualty of a calendar. Curiosity cannot, because curiosity is the one leadership behavior no pipeline can perform on your behalf. I spent years refusing to sign releases I hadn't read; that refusal is where 99.9% came from. A loop that asks its leaders to evaluate candidates they haven't read is asking them to sign unread releases — and the signature still certifies something. It certifies the culture. A process this incurious about evidence is usually attached to an organization that runs the same way inside.

How mine actually ended

I promised timestamps.

On Friday, after the loop had concluded, the pipeline's automated agent sent a new requirement: all of my references, entered into the system, within 24 hours — or my candidacy would not be considered. So I made the calls you make. The EVP and the CTO of that fintech — the executives from the December story, the people who keep my number for 6 AM — stopped what they were doing inside a nine-figure-revenue company and wrote recommendations against a weekend deadline set by software. They followed through.

Monday, 5:00 PM Pacific: the automated rejection. No reason attached. Not a sentence.

Lay the sequence out, because sequence is the indictment. The loop heard the December story told live, and checked the clock. The system then subpoenaed that story's witnesses on 24 hours' notice. The witnesses appeared and vouched. The system rejected the file — by every observable sign, unread. Three chances to ingest human evidence; zero taken. Plus one burned afternoon of executive attention at a company that had nothing to do with any of this. The blast radius of a broken loop extends well past the candidate.

One more cut, the gentlest. "You have my email address," a leader told me at the close of a call — sincerely — "feel free to reach out." I never had it. Every channel I was ever given belonged to the automated agent. A sincere open door with no handle on my side — so when the rejection came, there was no human left to ask why. That asymmetry tells you who the system believes is disposable.

Blameless, specific, aimed at the process

I own this piece without ego, in the same spirit I used to sign release notes. Everyone I met was pleasant. The recruiter was candid. The product leader was generous with a half hour he didn't have. The tape contains no villain — every indignity in it was produced by defaults nobody chose, running unattended. That is precisely what makes it worth writing down.

So here is the ask, addressed to every engineering leader who made it this far. Audit your funnel: count the hours of candidate time it consumes against the minutes of genuine evaluation it contains. Retire the puzzle theater for senior roles and interview against the actual job. Let candidates use the tools the job allows, and grade their judgment about the output. Read what references write before your software answers for them. And close every loop with a reason — because the silence is data too, and it's going in posts like this one.

The industry is sitting on a generation of systems-aware engineers — people who came up through hardware, networks, operations, the unglamorous load-bearing layers — at the exact moment AI has made algorithm recall worthless and systems judgment priceless. Engineering excellence was never the smartest person in the room. It was the honest process in the room. The companies that redesign hiring around that will staff the next decade. The ones that keep counting islands will keep wondering why the ocean looks empty.

"You have my email address," they told me. Kindly. Incorrectly. Here's one that works: if you've been through a loop like this — either side of the table — I want to hear it. I'll respond to every comment.

Go To Do Rust

Andrei Merlescu — Thu, 09 Jul 2026 15:15:12 +0000

In this post, I want to go from step by step what it would look like building a taskr binary in both Go and Rust side by side so you can see conversion conventions and why Rust wins in the battle between the gopher and the crab.

Starting Point

package main

import "fmt"

func main() {
   fmt.Println("Hello World")
}

fn main() {
   println!("Hello World")
}

From both of these applications, you should be working in a directory structure that looks like:

~/work/personal/learning-go/taskr/main.go
~/work/personal/learning-rust/taskr/main.rs

To get the ~/work/personal/learning-go directory, create it and then create a new Go file using:

mkdir -p ~/work/personal/learning-go/taskr
cd ~/work/personal/learning-go/taskr
go mod init taskr

To get the ~/work/personal/learning-rust/taskr directory, run:

mkdir -p ~/work/personal/learning-rust
cargo new taskr

From that command you'll get a Cargo.toml file which will be versioned to 0.1.0.

The program's data structure

We're building out a task, so lets define what that looks like in Go and in Rust.

type Status string

const (
    StatusTodo Status = "Todo"
    StatusDone Status = "Done"
)

type Task struct {
    ID     uint32 `json:"id"`
    Title  string `json:"title"`
    Status Status `json:"status"`
}

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
enum Status {
    Todo,
    Done,
}

#[derive(Debug, Serialize, Deserialize, Clone)]
struct Task {
    id: u32,
    title: String,
    status: Status,
}

Decorator	Usage
`Debug`	lets me print the value using `{:?}` format
`Serialize`	generate JSON code at compile time
`Deserialize`	read JSON code at compile time
`Clone`	allows you to duplicate a value
`PartialEq`	allows equality comparisons between Status values

These decorators will be used throughout the program later. Specifically, the Debug will be used in println!() statements. serde import provides Serialize and Deserialize in order to engage with JSON files at compile time. Without PartialEq, the status would not be comparable. It's required.

Let's define what the print_usage() function is going to look like in Go and in Rust.

func printUsage() {
    fmt.Println("taskr - A simple task manager")
    fmt.Println()
    fmt.Println("Usage:")
    fmt.Println("  taskr add <title>    Add a new task")
    fmt.Println("  taskr list           List all tasks")
    fmt.Println("  taskr done <id>      Mark a task as done")
    fmt.Println("  taskr delete <id>    Delete a task")
    fmt.Println("  taskr search <query> Search for a task")
}

fn print_usage() {
    println!("taskr - A simple task manager");
    println!();
    println!("Usage:");
    println!("  taskr add <title>    Add a new task");
    println!("  taskr list           List all tasks");
    println!("  taskr done <id>      Mark a task as done");
    println!("  taskr delete <id>    Delete a task");
    println!("  taskr search <query> Search for a task");
}

This should go above the main() func in both main.go and main.rs respectively.

Command	About
`taskr add <title>`	Add a new task
`taskr list`	List all tasks
`taskr done <id>`	Mark a task as done
`taskr delete <id>`	Delete a task
`taskr search <id>`	Search for a task

Implementing the print_usage() func in both Go and Rust is very simple and is done in the main() func respectively:

func main() {
    if len(os.Args) < 2 {
        printUsage()
        return
    }
}

fn main() {

    // .collect() returns the .args() into a Vec<String> format
    let args: Vec<String> = std::env::args().collect();

    // ensure that there are enough arguments to run the program
    if args.len() < 2 {
        print_usage();
    }
}

The big difference here is the Go os.Args and the Rust std::env::args().collect(). Clearly, Rust is more verbose, and without .collect() the value of the .args() could be a tuple of <String, Err>, but .collect() returns a Vec<String> if there are no Err thrown.

With this basic program functionality, we can implement in the main() func in both languages what that switching is going to look like parsing the 2nd and 3rd arguments respectively.

func main(){ 
    // ... existing

    switch args[1] {
        // 1. taskr search <query>
        case "search":

        // 2. taskr add <title>
        case "add":

        // 3. taskr list
        case "list":

        // 4. taskr done <id>
        case "done":

        // 5. taskr delete <id>
        case "delete":

        // 6. taskr <else> catch-all
        default:

    }

    //- end of main
}

fn main() {
    // ... existing

    match args[1].as_str() {

        // 1. taskr search <query>
        "search" => {}

        // 2. taskr add <title>
        "add" => {}

        // 3. taskr list
        "list" => {}

        // 4. taskr done <id>
        "done" => {}

        // 5. taskr delete <id>
        "delete" => {}

        // 6. taskr <else> catch-all
        _ => {
           eprintln!("Invalid command");
            print_usage();
            std::process::exit(1); // SIGTERM 1
        }

    } //- match arg[1]

    //- end of main
}

The match (rust) and switch (go) statements are both reading from args[1]. The 0 in args[0] would be the filename of the binary running. In the example of taskr list, the args[0] is taskr and args[1] is list. In rust, the .as_str() is used to ensure that the underlying type is a string, since the statement is a String in "statement" => { } (rust) and case "statement": (go).

Next, we are going to be implementing the TaskStore, but before we do that, we need to ensure that our programs respectively have the correct imports.

import (
    "encoding/json"
    "errors"
    "fmt"
    "os"
    "strconv"
    "strings"
)

// serde is used for JSON structure support at compile time
use serde::{Deserialize, Serialize};

// read and write on file functions
use std::fs;

// access the io::Result type for propagating I/O errors
use std::io;

// owned mutable file path
use std::path::PathBuf;

These imports allow each of the programs to respectively handle the functionality needed. Within Go, you'll interact with the os package for I/O related work and in Rust, you interact with std::io instead. Files are handled in Go using the os package, as well as the fs and ioutil packages. Rust consolidates it into a two packages called std::io and std::fs. Both languages are designed to be cross platform natively. One last thing to point out about this is the std::path::PathBuf and how its very similar to Go's filepath package offering. In Rust, the PathBuf type is specifically for filesystem paths. On Windows, you split your directory tree using \ and on Linux, you split your directory tree using /. Those differences are handled under the hood by the filepath (Go) and std::path::PathBuf (Rust) automatically.

The Task Store

The bulk of the logic of the application is going to expose TaskStore in both Go and Rust. How these are implemented matter and you'll see why that is.

type TaskStore struct {
    tasks    []Task
    filePath string
}

struct TaskStore{
    tasks: Vec<Task>,
    file_path: PathBuf,
}

Both of these snippets show you how similar Go and Rust can appear. The []Task in Go becomes a Vec<Task> in Rust and the filePath uses Rust's PathBuf. In Go, the struct can use and store the filePath as a string since filepath package returns only String types back - Rust gives you an entirely new type called PathBuf whereas Go gives you a wrapper for it.

When implementing the methods on the TaskStore, this is where Go and Rust diverge quite radically.

func NewTaskStore(filePath string) (*TaskStore, error) {}

func (s *TaskStore) Save() error {}

func (s *TaskStore) Add(title string) {}

func (s *TaskStore) Complete(id uint32) error {}

func (s *TaskStore) Delete(id uint32) error {}

func (s *TaskStore) List() {}

func (s *TaskStore) Search(query string) []*Task {}

impl TaskStore {

    fn new(file_path: PathBuf) -> io::Result<Self> {}

    fn save(&self) -> io::Result<()> {}

    fn add(&mut self, title: String) {}

    fn complete(&mut self, id: u32) -> Result<(), String> {}

    fn delete(&mut self, id: u32) -> Result<(), String> {}

    fn list(&self) {}

    fn search(&self, query: &str) -> Vec<&Task> {}
}

There is a pretty clean 1:1 relationship between the implemented methods of the TaskStore between Go and Rust and specifically what I want to note here for you is how in Rust everything is wrapped inside of the impl TaskStore {} block itself, whereas in Go, this can be literally anywhere at the root level of the file inside the package main project. The order of the routes does not matter in either language.

Rust has a convention called io::Result<Self> which in Go simply looks like (<Type>, error). The NewTaskStore method in Go is unattached per-se to the TaskStore struct itself, but it does return the Go equivalent of (*TaskStore, error) as io::Result<Self>. When io::Result<Self> is used, the method must also include Ok(()) in order to satisfy the contract.

At this point, let's ensure that our Go program has two little helper functions in it in order to improve runtime readability - this is common in Go.

func parseID(arg string) uint32 {
    id, err := strconv.ParseUint(arg, 10, 32)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Invalid task ID: %s\n", arg)
        os.Exit(1)
    }
    return uint32(id)
}

func mustSave(s *TaskStore) {
    if err := s.Save(); err != nil {
        fmt.Fprintf(os.Stderr, "Error saving tasks: %v\n", err)
        os.Exit(1)
    }
}

This application does not need or use helper functions in the Rust implementation. In Rust we're using u32 for the id and in Go that is a uint32 which imports the strconv package. Rust does not need to import any packages.

Before implementing the specifics in the TaskStore, lets consume it in the main() func.

func main() {

    // ... after checking the length of args

    store, err := NewTaskStore("tasks.json")
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error loading tasks: %v\n", err)
        os.Exit(1)
    }

    // ... before switching args[1]

}

fn main() -> io::Result<()> {

    // ... after checking the length of args

    let database = PathBuf::from("tasks.json");

    let mut store = match TaskStore::new(database){
        Ok(store) => store,
        Err(e) => {
            eprintln!("Error loading tasks: {}", e);
            std::process::exit(1); // SIGTERM 1
        }
    };

    // ... before matching args[1]

}

Both of these implementations will leverage the current working directory and consume the resource tasks.json if it exists. If it does not exist, the program will create it, if it exists, the program will overwrite it.

In Rust, the TaskStore is consumed slightly differently than in Go because of the impl TaskStore {} differences. In Rust the TaskStore must have mut after let and before the name of the variable in order to indicate to the compiler that the value of store is eligible for changing in the future. Since the TaskStore::new(database) returns with an io::Result<Self>, we can match against it when assigning it to the store variable.

The Go tuple that io::Result<Self> is satisfying is (*TaskStore, error) and in Rust, the first component *TaskStore is represented in by the Ok() invocation. At the end of the various impl TaskStore {} methods, you'll see an Ok(()) at the end of each method ; this invokes the contract and exits the method since we're good. Otherwise, your program will not compile. When assigning a value to store and executing TaskStore::new(database), each component of the output gets matched to the Ok(store) => or Err(e) => {} blocks respectively. When we receive an Ok(()) then that returned store from Ok() is then assigned to the let mut store variable.

Otherwise, if Err(e) satisfies, it means that something went wrong and we'll print the error and exit with status code 1. In Go, we use os.Exit(1) and in Rust we use std::process::exit(1);. In Go, we can use the fmt or slog or verbose packages to write to STDOUT and STDERR, and in Rust we use eprintln!() for STDERR and println!() for STDOUT respectively.

Implementing new `TaskStore`

We have stubbed out each of our methods, and at this point we need to implement the body of these methods in two locations. We're going to implement the TaskStore now, and that means populating each of the methods in TWO locations. First in the impl TaskStore {} block for Rust and inside of the func (s *TaskStore) ... methods for Go.

Method	Go Signature	Rust Signature
`new`	`func NewTaskStore(filePath string) (*TaskStore, error)`	`fn new(file_path: PathBuf) -> io::Result<Self>`
`save`	`func (s *TaskStore) Save() error`	`fn save(&self) -> io::Result<()>`
`list`	`func (s *TaskStore) List()`	`fn list(&self)`
`complete`	`func (s *TaskStore) Complete(id uint32) error`	`fn complete(&mut self, id: u32) -> Result<(), String>`
`delete`	`func (s *TaskStore) Delete(id uint32) error`	`fn delete(&mut self, id: u32) -> Result<(), String>`
`add`	`func (s *TaskStore) Add(title string)`	`fn add(&mut self, title: String)`
`search`	`func (s TaskStore) Search(query string) []Task`	`fn search(&self, query: &str) -> Vec<&Task>`

TaskStore's `new` Implemented

func NewTaskStore(filePath string) (*TaskStore, error) {
    tasks := []Task{}

    data, err := os.ReadFile(filePath)
    if err == nil {
        if jsonErr := json.Unmarshal(data, &tasks); jsonErr != nil {
            tasks = []Task{}
        }
    } else if !errors.Is(err, os.ErrNotExist) {
        return nil, err
    }

    return &TaskStore{tasks: tasks, filePath: filePath}, nil
}

fn new(file_path: PathBuf) -> io::Result<Self> {

    let tasks = if file_path.exists() {
        let data = fs::read_to_string(&file_path)?;
        serde_json::from_str(&data).unwrap_or_else(|_| Vec::new() )
    } else { 
        Vec::new()
    };

    Ok(Self { tasks, file_path })
}

The most notable thing to understand in this code block is the difference between how Go and Rust respectively handle JSON. To be clear up front: both languages parse the actual data at runtime — no compiler can validate a file that doesn't exist until the program runs. The real difference is where the mapping code comes from and how failure is surfaced. In Go, json.Unmarshal uses reflection at runtime to inspect your struct's fields and figure out how to map the data onto them, and it reports problems as an error value you check with jsonErr != nil — a check the compiler will let you skip entirely. It's also forgiving by default: unknown fields are ignored and missing fields silently become zero values, so irregular JSON can flow through your program without any error at all. In Rust, the #[derive(Deserialize)] macro generates the mapping code at compile time — no reflection — and the build fails outright if any field's type can't be deserialized. At runtime, serde_json::from_str returns a Result, and the type system won't let you touch the parsed value until you've decided what happens on failure — with ?, a match, or a fallback like .unwrap_or_else(|_| Vec::new()). Mistyped or missing fields are loud errors by default instead of silent zero values, and the generated code is typically faster than reflection-based decoding as a bonus. Ultimately, Rust doesn't validate your JSON before compilation — it forces you to handle irregular JSON before your code will compile, which is what actually takes the sting out of the most painful part of Go development: interacting with irregular JSON files.

Literally, modeling an irregular JSON file in Rust can take you noticeably longer to get right than in Go — every optional field, inconsistent type, and quirk has to be spelled out with Option<T>, #[serde(default)], or a custom deserializer before the compiler lets you move on. The investment of time in this, on the surface, feels like it's a waste and unnecessary — but years down the road, the payoff arrives at runtime, not at recompile time: when that feed inevitably changes shape, the Rust program fails loudly at the parse boundary, while the Go program may keep running on silent zero values. What neither language will do is pull the rug out from under old code. Go's compatibility promise explicitly guarantees that programs written for Go 1 keep compiling and behaving the same — encoding/json included — and even the new encoding/json/v2 ships as a separate, opt-in package rather than a change to the old one. Rust makes the same commitment through its edition system: new editions are opt-in per crate, and old ones keep compiling on new compilers (rare soundness fixes aside). So who actually gives you write once, compile 25 years later with zero effort? C mostly does, though modern compilers now reject old habits like implicit int. C++ mostly does, though the standard really does remove things — auto_ptr, register, pre-standard headers — so "zero effort" is optimistic. Rust hasn't existed long enough to prove it (1.0 shipped in 2015), but its stability policy is built for exactly that. And Go, far from merely trying, has one of the strictest backward-compatibility records in the industry. As for Python, PHP and Ruby — their major-version breaks (Python 2→3 most famously) are stewardship choices, not something true by definition and design of high-level languages; and "compile 25 years later" isn't quite the right test for interpreted languages anyway.

We consumed the new method in the main() func when we established our let mut store (rust) and store, err := NewTaskStore("tasks.json") (go).

TaskStore's `list` Implemented

func (s *TaskStore) List() {
    if len(s.tasks) == 0 {
        fmt.Println("No tasks yet. Add one with: taskr add \"your task\"")
        return
    }

    for _, task := range s.tasks {
        marker := "[ ]"
        if task.Status == StatusDone {
            marker = "[X]"
        }
        fmt.Printf("%s %d - %s\n", marker, task.ID, task.Title)
    }
}

fn list(&self) {
    if self.tasks.is_empty() {
        println!("No tasks yet. Add one with: taskr add \"your task\"");
        return;
    }

    for task in &self.tasks {
        let market = match task.status {
            Status::Todo => "[ ]",
            Status::Done => "[X]",
        };
        println!("{} {} - {}", market, task.id, task.title);
    }
}

Respectively, these two methods look pretty much the same. Specifically in Rust we're leveraging the borrower for &self.tasks and in Go we just range over them without needing to indicate memory usage. Without the Debug derived decorator attacked to the Task struct, the println!() methods that use {} wouldn't compile.

TaskStore's `add` Implemented

func (s *TaskStore) Add(title string) {
    var maxID uint32
    for _, t := range s.tasks {
        if t.ID > maxID {
            maxID = t.ID
        }
    }

    task := Task{
        ID:     maxID + 1,
        Title:  title,
        Status: StatusTodo,
    }

    fmt.Printf("Added task %d: %s\n", task.ID, task.Title)
    s.tasks = append(s.tasks, task)
}

fn add(&mut self, title: String) {
    let id = self.tasks.iter() // use the iterator
        .map(|t| t.id)         // use only the id field
        .max()                 // select the maximum value in the set
        .unwrap_or(0) + 1;     // if no err, use # else use 0 + 1

    let task = Task {
        id,                    // short for `id: id,`
        title,                 // short for `title: title,`
        status: Status::Todo,
    };

    println!("Added task {}: {}", task.id, task.title);

    self.tasks.push(task);
}

Most notably between this Go and Rust code you can see the manner for acquiring the next ID in the set is radically different. In Rust we are using the .iter() in order to .map() then .max() with a final check of .unwrap_or(0) in order to get an iterable list of IDs via the .map() extraction of just the id field, followed by the .max() choice. This quickly returns the largest integer of the result and then attempts to + 1 at the end of it. In Rust this expression is a simple statement and in Go its multiple lines using maxID inside the method.

In Rust without the &mut on the self argument of the method, the self.tasks.push(task); would fail because the compiler is missing the &mut on self in order to actually write via .push(). In Go, we simply use append(...).

Both languages now need to take this impl TaskStore { "add" => {} } and func (s *TaskStore) Add(title string) and consume them in the main() func.

func main() {
    // ... existing after \`switch args[1]\`

    case "add":
        if len(args) < 3 {
            fmt.Fprintln(os.Stderr, "Usage: taskr add <title>")
            os.Exit(1)
        }
        store.Add(strings.Join(args[2:], " "))
        mustSave(store)
    }

    // ... existing before \`default:\` case 
}

fn main() {

    // ... existing after `match args[1].to_str() {`

    // 2. taskr add <title>
    "add" => {
        if args.len() < 3 {
            eprintln!("Usage: taskr add <title>");
            std::process::exit(1); // SIGTERM 1
        }
        let title = args[2..].join(" ");
        store.add(title);
        store.save()?;
        Ok(())
    }

    // ... existing before `_ => {}` match
}

Our Go code is consuming the mustSave helper method and our Rust code is calling .add() and .save() endpoints on the TaskStore impl.

TaskStore's `delete` Implemented

func (s *TaskStore) Delete(id uint32) error {
    for i, t := range s.tasks {
        if t.ID == id {
            fmt.Printf("Removed task %d: %s\n", t.ID, t.Title)
            s.tasks = append(s.tasks[:i], s.tasks[i+1:]...)
            return nil
        }
    }
    return fmt.Errorf("task %d not found", id)
}

fn delete(&mut self, id: u32) -> Result<(), String> {
    let pos = self.tasks.iter()       // get an iterator
        .position(|t| t.id == id)     // find the index of the id
        .ok_or_else(|| 
            format!("Task {} not found", id)
        )?;

    let removed = self.tasks.remove(pos);
    println!("Removed task {}: {}", removed.id, removed.title); 
    Ok(()) 
}

As you can see - these methods look so similar and that's because Go and Rust compliment each other, like C and C++ complimented each other. They are designed to be similar, but one for more lower level work and the other for more higher level data driven work. Either way, when you implement these methods, you see their implementations even look similar.

case "delete":
    if len(args) < 3 {
        fmt.Fprintln(os.Stderr, "Usage: taskr delete <id>")
        os.Exit(1)
    }
    if err := store.Delete(parseID(args[2])); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    mustSave(store)

"delete" => {
    if args.len() < 3 {
        eprintln!("Usage: taskr delete");
        std::process::exit(1);
    }
    let id: u32 = args[2].parse().unwrap_or_else(|_| {
        eprintln!("Invalid task ID: {}", args[2]);
        std::process::exit(1);
    });
    if let Err(e) = store.delete(id) {
        eprintln!("{}", e);
        std::process::exit(1); // SIGTERM 1
    }
    store.save()?;
    Ok(())
}

Most notably in the differences between these two implementations, you can see the Go helper method parseID being used here where Rust just leverages .parse().unwrap_or_else(|_| {} ) instead.

TaskStore's `complete` | `done` Implemented

func (s *TaskStore) Complete(id uint32) error {
    for i := range s.tasks {
        if s.tasks[i].ID == id {
            s.tasks[i].Status = StatusDone
            fmt.Printf("Completed task %d: %s\n", s.tasks[i].ID, s.tasks[i].Title)
            return nil
        }
    }
    return fmt.Errorf("task %d not found", id)
}

fn delete(&mut self, id: u32) -> Result<(), String> {
    let pos = self.tasks.iter()    // get an iterator
        .position(|t| t.id == id)  // find the index of the id
        .ok_or_else(|| 
            format!("Task {} not found", id)
        )?;

    let removed = self.tasks.remove(pos);
    println!("Removed task {}: {}", removed.id, removed.title); 
    Ok(())
}

The conventions between Rust and Go become very visibly noticeable in this manner of presentation.

case "done":
    if len(args) < 3 {
        fmt.Fprintln(os.Stderr, "Usage: taskr done <id>")
        os.Exit(1)
    }
    if err := store.Complete(parseID(args[2])); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    mustSave(store)

"done" => {
    if args.len() < 3 {
        eprintln!("Usage: taskr done");
        std::process::exit(1); // SIGTERM 1
    }
    let id: u32 = args[2].parse().unwrap_or_else(|_| {
        eprintln!("Invalid task ID: {}", args[2]);
        std::process::exit(1); // SIGTERM 1
    });
    if let Err(e) = store.complete(id) {
        eprintln!("{}", e);
        std::process::exit(1); // SIGTERM 1
    }
    store.save()?;
    Ok(())
}

TaskStore's `search` Implemented

func (s *TaskStore) Search(query string) []*Task {
    queryLower := strings.ToLower(query)
    var results []*Task
    for i := range s.tasks {
        if strings.Contains(strings.ToLower(s.tasks[i].Title), queryLower) {
            results = append(results, &s.tasks[i])
        }
    }
    return results
}

fn search(&self, query: &str) -> Vec<&Task> {
    let query_lower = query.to_lowercase();

    self.tasks.iter()                    // get an iterator
        .filter(|task|                   // each task loop
            task.title.to_lowercase()    // get lowercase title
                .contains(&query_lower)  // match with query_lower
        )
        .collect()                       // gather into vector
}

Specifically, the Rust is returning Vec<&Task> which is a referenced object explicitly from the .collect() output.

case "search":
    if len(args) < 3 {
        fmt.Fprintln(os.Stderr, "Usage: taskr search <query>")
        os.Exit(1)
    }
    query := strings.Join(args[2:], " ")
    results := store.Search(query)
    if len(results) == 0 {
        fmt.Printf("No tasks found matching %q\n", query)
    } else {
        fmt.Printf("Found %d tasks matching: %s\n", len(results), query)
        for _, task := range results {
            marker := "[ ]"
            if task.Status == StatusDone {
                marker = "[X]"
            }
            fmt.Printf("%s %d: %s\n", marker, task.ID, task.Title)
        }
    }

"search" => {
    if args.len() < 3 {
        eprintln!("Usage: taskr search <query>");
        std::process::exit(1); // SIGTERM 1
    }

    let query = args[2..].join(" "); 
    let results = store.search(&query);

    if results.is_empty() {
        println!("No tasks found matching \"{}\"", query);
    } else {
        println!("Found {} tasks matching: {}", results.len(), query);
        for task in &results { 
            let marker = match task.status { 
                Status::Todo => "[ ]", // incomplete items
                Status::Done => "[X]", // completed items
            };
            println!("{} {}: {}", marker, task.id, task.title);
        }
    }

    Ok(())
}

Conclusion

You can view the Go and Rust full source code respectively at either link provided.

This tutorial was designed to help bring Go engineers over to Rust by completing a command line task manager application in both languages to see how they are both the similar and different.

Are you coming into Rust from Go like I am? If so, what are some of your favorite resources to use and learn from?

When AI Creates A Closed Source World

Andrei Merlescu — Thu, 02 Jul 2026 16:22:12 +0000

This hit me hard. I contributed thousands of hours of labor into this library and for what? To be kicked out after somebody else starts charging admission for it? Jobs are extremely difficult to come by now?

What is "The Library"?

The aggregate collection of text contributed by any given single individual is known as The Library. This Library that became AI through a large language model was a gathering of each The Library from the collective mind — mine included — yours included perhaps — ingested into their algorithms for predictive text generation.

Many times I would find myself reading StackOverflow™ in a bind between wanting to figure out my thing and correct the record when a post didn't quite get what I needed correct. That back and forth, contributed by me — and by you perhaps — was The Library that these AI companies possessed (nicest way to describe legal theft) and then turned into a subscription. A subscription based on usage now, not even time. How much do you need The Library and how much are you willing to pay? That's what Dario is looking for. That's what Sam is looking for.

My figtree package is in The Library in a way that is both seen and unseen. I didn't consent to that work being uploaded, so why do I pay a subscription to access The Library that contains my works *and their predictive derivatives? Those predictive derivatives are where the intellectual property is captured beyond the raw code itself — the *between the lines meaning from project A to project B, what a competitor or bad actor could make against my own efforts.

The Problem With Open Source

I have contributed 99+ open source packages on GitHub. I'm a 5-digit user ID from 2009. And I see a problem with open source in 2026.

Look at what happened in June. Anthropic launched Fable 5, and within three days the US government invoked national security export controls and forced it offline worldwide. Think about what that means: models trained on our freely-given contributions are now considered so dangerous they get handled like weapons. Knowledge went in open and unconsented. It came out closed, priced, and government-controlled.

So why would I release anything open source anymore? Sam, Dario and Elon — along with thousands of others — will just take the work, incorporate it into the LLM itself, and use my own knowledge against me. I would be foolish to think open source could survive this. Any engineer who runs the numbers arrives at the same place: closed source is the future. Private repos. Stop training your replacement for free.

I ran those numbers too. I arrived at the same place.

Romania

And then I remembered that I have already lived in a closed-source world.

I've been involved in the internet since the day I arrived in the United States from Romania — the era when the University of Maine ran BITNET, before the good people of Maine had access to TCP/IP. My programming career began at 9 years old because of the University. By 11 I had the internet. In 1994 I was doing computer work beside my mother in Neville Hall in Orono — the same building that ran the state of Maine's connection. Nobody charged us admission. Thousands contributed willingly because the incentive was to learn and better yourself, and an orphan from Ceaușescu's Romania became an engineer at Cisco, Oracle, and WB Games because that door was open.

The Internet is going through a revolution like Romania did after Ceaușescu's Christmas Present 1989, and AI caused it. But I know what grows behind closed doors. I grew up in it.

So No

Everything above this line says I should close my source. I'm not going to, and you should know it's not because the theft isn't real — it is, and I want it remedied: disclosure of training data, consent for future ingestion, compensation for what was taken.

But somewhere there is another 11-year-old at a public terminal, and my code costs them nothing.

Don't close-source your contributions for anyone's bottom line. Be like me — Andrei — and continue giving selflessly, expecting nothing in return, more useful open source utilities that the greater good actually needs.

Why do you still publish open source — or why did you stop? I'll respond to every comment.

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.

DEV Community: Andrei Merlescu

Sovereign Lemmings Released

Topobuilder brings a cPanel website into an AWS multi-region containerized application with an HAProxy load balancer

Go Application Design

The verbose package

The models package

Why I Built This

Conclusion

The Day I Stopped Asking Strangers for My IP

A Story of Go, systemd, and SELinux Left Enforcing

Meet the binary

Step 1 — Acquire it

Step 2 — Teach systemd about it

Step 3 — run-app.sh, or: how to befriend SELinux instead of shooting it

The sermon

Low ports without root

Step 4 — Let systemd take the wheel

Step 5 — The config file

Step 6 — Light it up

Why this matters beyond your homelab

Conclusion

Five Hours Of Interviewing - Zero Questions About The Job

Go To Do Rust

Starting Point

The program's data structure

The Task Store

Implementing new TaskStore

TaskStore's new Implemented

TaskStore's list Implemented

TaskStore's add Implemented

TaskStore's delete Implemented

TaskStore's complete | done Implemented

TaskStore's search Implemented

Conclusion

When AI Creates A Closed Source World

What is "The Library"?

The Problem With Open Source

Romania

So No

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

The `verbose` package

The `models` package

Implementing new `TaskStore`

TaskStore's `new` Implemented

TaskStore's `list` Implemented

TaskStore's `add` Implemented

TaskStore's `delete` Implemented

TaskStore's `complete` | `done` Implemented

TaskStore's `search` Implemented

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