Noah Roberts's blog

Contact Form Project 05: Error Handling

2026-10-18T00:00:00Z

In the last installment I became disappointed with myself for not doing adequate error handling. It's early in the project so I became tempted to skip that and put it off for later. I decided while writing my blog entry that I'd made a bad decision and one that could be used as a teaching moment. I've since gone back and fixed that issue.

Process error codes

A lot of times the exit code that your process returns means more than just pass/fail. A great many projects stipulate codes for different conditions and if your program is meant to be used by an automated system it can be important. So I spent a lot of time learning how to do this in Rust.

This can be done if you make your own object that responds to the Termination trait. I was able to follow much of this blog to get there. Unfortunately though I couldn't get as far as implementing ? from that blog entry because the interface to do so has changed from v1 to v2 and v2 is completely different from v1. The Try trait now works with "Residuals" and I struggled to understand the setup. I tried just getting it done by using "try_v2" to get the derive macro but this didn't work immediately.

This can only be done by using "unstable" rust API. I decided I didn't want to do that and instead of learning this now anyway I'll pick it up later. I could either just not use ? in main or I could give up on the idea of error codes for each type of error. I decided on the latter so I just let rust report the error when it exits and return ExitCode::FAILURE per the default behavior when you return a Result.

Error type scheme

There are a bunch of different ways in which people handle errors in Rust. The most common ones obviously use Result or Optional, but there's also a lot of differences in the Error type used and how rigorous the API is about what errors come out of what functions.

I decided that I don't really care that much for the conditions I have need ot dealing with so far. I already selected axum for the server library and it makes sure all errors are handled, so I just need to handle the conditions that prevent me from handing off to this library by calling serve. So I went with the anyhow library. This just wraps up the errors in something dynamic I can hand up the change to the part that reports the condition to the user and exits. Rust has another method of dealing with these, panic, but I'm maybe too into the idea I should propagate up more expilicitly.

This anyhow library lets me attach further context to the error so when it gets reported it provides additional information on top of whatever got discovered by the error generation part. Here's an example:

let listener = tokio::net::TcpListener::bind(&self.config.listen_address)
    .await
    .with_context(|| format!("Could not bind network interface at `{}`", &self.config.listen_address))?;

This is a little sloppier than I'm usually comfortable with--just mashing all error types into one bucket-- but in this case I think I really need to silence that part of my brain and be good with this. There's no need to do more than this at this time and I don't think there ever will be.

So after a couple days of messing about coming up with ways to propagate the info up with explicit errors at each level, and not being happy with any of it, I decided that this anyhow library is what I want. The same author makes another helpful library for custom errors but I don't think I'm going to go that way.

Contact Form Project 04: Beginning Implementation

2026-10-06T00:00:00Z

The last installment was not really finished but I just published it anyway. I lost track of doing this blog as I advanced in the project. Last time I talked a bit about the testing. Since then I've implemented the very first real behavior and checks. I also did a lot of work on the build system so that it can do partial rebuilds instead of recalculating all the certificates for each build.

Using Rust

The act of learning rust at the same time has proven to be a hurdle at times. It's going quite well, and the language's compiler is very helpful here, but there's still a bunch I don't know and I keep making mistakes that are difficult to resolve. I do really like the language so far, but if this was hard-engineered product I wouldn't have chosen Rust because I don't know enough about it. I'm stumbling around until stuff works and though I'm basing this on the documentation and I'm picking up the reasons why things are broken--it's just impossible to anticipate how long stuff is going to take me and the end product is not going to have the sort of confidence that is necessary for tightly regulated software development.

I do feel I can do a good enough job with this though so I'm not worried about that here. I understand the sorts of problems that come up in languages like Rust that are close to the machine and the compiler for this language really is very helpful. I'm also confident that I'm picking up what I need to so that I will understand better soon. It's like C++ but it's also very different. The patterns it encourages are patterns I've used in C++ but are more difficult/complicated there. Traits are similar to "policies" in Alexandrescu's "Policy Based Design" constructs in his "Modern C++" book, for example. There's much more freedom with Traits though.

Messing up rigor

I moved past the step of "simple configuration" and accepted that as "done" before I should have. It still panics if you don't supply a file name. Still panics if there are parse errors I'm sure but I don't know because I haven't tested that.

This step isn't a complete feature. The actual format of the configuration file is mostly irrelevant and is going to change significantly. How it's provided to the program isn't completely set either and may change. I was tempted by these facts, the desire to learn more and get more designed, and the desire to make more progress sooner. This is instant technical debt though and is just damn sloppy. Even though I'm just sort of throwing this together to have a base, that base needs to be more solid than this. Yes, I need to waste my time making sure errors are handled that are just going to be impossible later. Yes, I need to waste my time testing to make sure those errors are handled.

You're not doing actual incremental development if you are postponing "finish" work for later. To adhere to agile principles in order to call this task "done" I need to make sure it follows the requirements of the system and one of those is that it handles errors correctly. Each feature should be "done" before it is said it is "done" even if "done" isn't anything like what it will be when everything is "done". The reason is simple: if you don't then this stuff slips through the cracks to production.

If you do have some item that maybe can't be completed in this way or would be too expensive to or whatever then the exception needs to be made in the forefront. I did not plan it that way. If you do then you'll have the finishing of this created as a future item already. Or perhaps you call this a scaffold and it doesn't even label anything as completed in the plan but is instead part of the feature item it's needed by.

At any rate, you don't do what I did. Don't approve items that haven't been really reviewed and don't approve items as 'done' if they fail to meet that definition. So I'll be going back to fix this before I continue with what I was going to do next: the "authentication" scheme.

CMake meta build

I got tired of having every image basically have to be rebuilt because the CA test keys got built every time. I wanted to have a system that knows dependencies and can do incremental builds. I picked CMake because I'm fairly familiar with it and it does everything I need it to.

This area I feel I got pretty good but I have yet to see it tested by someone else or on systems that aren't basically my own setup. The combination of nix, docker, pytest, and cmake form a develop and test bench that should be pretty close to turn-key. I have a few kinks to work out I think but it's dialing in. You should be able to follow the README.md file to get a build and run the tests and there's only a couple base dependencies and commands you need to run.

Moving forward

This blog is probably going to continue to suffer. This project isn't going to so much serve as an example of how to do this but more a practice bench for myself to hone my processes. Then I can document those and maybe convert that into teaching material.

Current code state

Contact Form Project 03: A testing system

2026-09-24T00:00:00Z

In the previous installment I linked to a plan I'd created that had the first set of tasks about designing a base test system that provides automation for testing. In this one I'll talk a bit about what I did to accomplish that and how to look it over and reproduce my work (run the test successfully).

git-bug issues

I also talked about modifying a couple requirements last time and that I needed to track issues somehow. I did decide to experiment with git-bug and so that's become a part of the process here. Unfortunately, it looks to me like I didn't verify it was usable if I deleted my current working copy because it isn't in the copy I made to verify my test process can be recreated. So before I talk about how to use that system I have to figure out how to fix it and may be changing my mind about using it.

The issue is that my user identity doesn't seem to be available to adopt before I pull and I can't pull without adopting my identity. This is fixed in the version they just released a couple days ago but I haven't updated yet. I've verified you can pull and review the issues if you want and have the latest git-bug:

git bug pull
git bug bug

It's not really going to tell you a whole lot right now though.

test design

The test design document describes how the tests are made to work. The system uses docker for now but I have plans to switch to podman to hopefully eliminate some issues with the setup, which reflect the fact that I'm pretty lazy about the security of my own development docker environment. There are a couple things I really wanted out of this:

testing takes place on a faked internet where the real thing can't be accessed.
tests can be fully automated including the setup/teardown of different faked internets.

The top diagram of the page describes the components. For now the implementation is just a "hello service" that returns "Hello, World!!!" when you do a get on its root resource.

A simple sort of certificate authority is made from shell scripts. The CA's certificate is registered as authoritative with the service and contact systems. The CA's certificate generation script is used to create keys and certificates for the form and service servers, which are used by them to be accepted by the service and contact systems and then encrypt traffic. I wanted to use ACME here but I'm going to figure that out later.

With the certificates made and the service built, some docker images can be built that have the necessary software and components to make a fake deployment. There's some shell scripts to do this building that are all tied together into /tools/build.sh.

Once that's done, networks can be created that have dnsmask to resolve domain names (docker has its own but this is simulating real names), any number of form systems, and any number of services that can run behind nginx-proxy images. Within this network the contact system can be available or join and then access the form or service to test it.

One example was made in single-form that just has one form system with one service system along with the dns resolver and a contact image that runs firefox such that it can be accessed from a browser on the localhost.

Automation is then added to this by having a testnet isolated network available that a contact system running selenium can join on which can also run another image that has pytest and docker-in-docker to both start up the test network the contact system is in and also control that system's selenium through webdriver.Remote in pytest scripts. An example test was created that starts up the single-form test network and then fetches the service message to validate it. This testnet is created by nix develop on entry but it doesn't then get deleted until the developer does or the system resets.

Why all of this?

It's important to make test automation a first-class citizen in the project plan and design. I've tried here to cover all the basic things I need from the test system. Namely that:

I'm able to automate most even if I can't use a free CI/CD server.
The system is tested in as close to the production environment as I can mimic.
My tests are isolated and aren't erroneously affected by the real world or visa-versa.

By using virtualization I can simuulate a great deal about the production environment in a way that doesn't alter the way the system has to behave. It may be additionally useful or preferable to use a completely virtualized system image but containers can do a lot here and can do enough for now. The original plan I had did hope I'd have an actual base system image I'd start with and then install things on and set up in virtual networks with kvm instead, but this implementation still sufficiently serves the purpose of exercising the design.

Contact Form Project 02: Project Beginnings

2026-09-17T00:00:00Z

In this post I'm going to go over the design a bit and some of the implementation I did yesterday. But first some things of note:

Questionable requirements

I think I still got a bit too much into my idea of what a secure form processing service will look like in my requirements. Two important examples are:

The service shall encrypt recipient data at rest.
The service shall encrypt all communications.

There are two very important security requirements for anything you actually put out there as a service. That's my opinion anyway and I do believe these are also pretty much verbatim out of OWASP. But should this service be responsible for this?

The answer is actually a very certain, "Absolutely not!"

This should be done by the operating/init system in the first case and by a proxy like traefic, nginx, or caddy in the second.

I've actually seen this mistake happen before and I just repeated it. Requirements to encrypt this or that got written in stone and then the implementation ended up being an utterly stupid response just to fulfill a requirement that maybe should not have been there to begin with.

If I were only using all of my "Design Manual" to help myself in creating the design, and yes I find all that diagram nonsense helpful, then I wouldn't bother going back and fixing this. I need to though. These requirements cannot stand as is and I intend a complete, coherent work package or as close as I can get without being reviewed (though good review is desired).

In a real SDLC, and especially one that needs to be compliant with 62304, 13485 and others, I would need to make sure this was traced in some way. This means that the reason why I was making the change is documented, what the actual change was, and that this change was approved all needs to be somewhere. The best way to do this is actually with an issue managment system that tracks an issue from creation, through commenting, approval, and to final resolution and acceptance.

In my final goal for my own process around all this these tickets are in git with the code. This is so the whole project everything is in one database and multiple forms of documents can be produced from it. There are projects that could form the basis of this such as git-bug and radicle that could help here. I may go ahead and pick up git-bug today to fix this problem just to have that record to work with even if it's not in perfect form--because I don't even know that that is yet.

What I need for these requirements is not part of the implementation but part of the deployment and thus the documentation. So there needs to be something to include those things because THAT is what I actually want: a documented (and hopefully scripted) process to delpoy the thing in a secure manner that encrypts data at rest and encryts traffic in/out of system nodes. I also need to add these deployment components to my architecture design.

Design

I worked on documenting a design that responded to requirements. It's only the very upper layers of architecture and process description that would form the documentation needed for a non-safety critical piece of medical software. You are expected to create a more detailed design but it doesn't need to be documented and submitted.

That's the idea I have anyway. I've seen some of this process work and read a great deal about it but some of my involvement was further away and the certifications I actually saw completed were relatively easy to get and not "medical grade" such as a CE mark.

The design I have to date is here. You'll note it's missing a response to one of the two requirements I flagged. The response I did for the other is flawed I think and should instead do the decryption in init and then pass the decrypted data to the service. I did consider that this means the service can't load the config in protected memory or something (with a crypt library maybe) but I think maybe that level of security here is unwarranted and impractical and may not even do anything beneficial. Deployment can then use an encrypted partition and/or some other secret management like maybe agenix.

Planning

I made a set of diagrams to help me plan out the project. I hope it's fairly accurate and adequately covers the documentation requirements I have set for myself, but it's possible that part could push me over. The dependency relationships between tasks already broke down considerably when it came to implementing but I believe everything is accounted for. Time will tell.

I'm tracking progress in that page in the design document. This is a stupid and pointless way to do this but I wasn't going to use ticketing. I may have changed my mind though due to wanting to do the tracing of change reason and to experiment with git-bug (I have to be very weary here because I get distracted into these side things easily). With that in mind it could be easier and better to generate this sort of documentation out of that system. This is what the Tidepool Open Source QMS does for a lot of things--they generate many of their submitted documents from their JIRA issue system and you can see this in their SOPs.

The plan has me creating a bunch of test support code first and a skeleton service. The system includes a way to build a fake internet on the test system and perform automated tests with various environment and service setups. It's actually pretty amazing how easy this part is going to be through modern tooling. In the past this sort of thing would have been more difficult and maybe require a cluster of physical computers. I've already got a lot of it running in docker.

Project status now

Next: Implementation

I've actually made some serious progress, but I don't like to have partial commits and I didn't quite finish yesterday. So you can't see it yet. But...

I did want to do this in nix or guix and may spend time on that if I have time, but decided to go with docker images for now. It's lighter and simple and I know a lot more about how to do it already. It might be better to use podman but I need to install it better in nix and don't want to mess with it right now. It makes little practical difference and will be easy to switch later.

What I have so far is a script that:

creates a root CA key and self-signed certificate
[temporary] creates a test server key and certifies it
creates a docker image that includes the root CA cert in its ca-certificates
creates a version of the nginx image that publishes to ssl and uses the test server key by default

I then have a couple compose setups that use dnsmasq and a private network with combinations of additional images that let me:

verify I can make a private internet where I can lie about domain resolution.
verify my base image correctly accepts server certificates signed by the CA root.

From here I intend to wire up my own ACME server to make dealing with the CA something I don't really have to think much about. This will be a fake Let's Encrypt to automatically get certificates.

Working branch

Contact Form Project 01: Project Initiation

2026-09-17T00:00:00Z

I'm very unhappy with the way I have contact set up here and at my business's website. One drawback of using static sites only is that I can't have any dynamic processing and so can't set up a form that sends an email--that option is sort of available but it's terrible and doesn't really work anymore.

There are other businesses I could pay to do this processing. These businesses set up a system whereby you can have your form content sent to your email in a more secure way. Web3Forms is an example. The objective being to:

hide your email address from wouldbe spammers
have a contact form that works if the user doesn't have an email client and/or email.

Web3Forms seems decent enough--I've not tried myself--but I'm also in need of a professional portfolio better than a work history in enterprise and medical. I also have to admit that that history doesn't have a lot of requirements analysis or planning in it and is mostly development, design, and mentorship. A contact form is a simple enough project to do some exercising of my own, play with some ideas in project management, maybe instruct a bit, and showcase what I can do in this area.

What's the project going to be?

I've started a lot of work in requirements analysis and design that I'll be talking about in this entry later. The brief of it is though that this will be a secure contact form server that I can configure for myself and my website clients (when I get some) that offers the sort of guarantees I want from such services. In doing so I'll be leveraging some quality controls that are really just in my head for now but are meant to protect user data from any and all unauthorized access.

In this I want to document some of my thoughts on how to design such systems and ensure that they work the way you say they do to the best of your ability. I can't go so far as to guarantee a lot of things because I don't have the expertise to say things like whether or not the claim that this or that algorithm is quantum secure is true or not. I have to trust that the experts are telling the truth. I can do my best though to apply their work as intelligently as possible.

Some things I'm doing the long way because I don't know of the right tool to do it the easy way. I'm sure these tools exist and can be tied together the way I want, but so far I've not found that solution and I need to get something done so--the size of this project makes it still possible to do what I want the way I want.

Starting out - Design Inputs

The 62304 process has "Design Inputs" feeding a "Design" process that results in "Design Outputs" that are then used as inputs to the next process in the Software Development Life Cycle (SDLC). Some managers and quality control people take this to mean that you have to do one, and then the other. I do not believe this to be the case, especially since the standards say so. What this tells us is that there's a dependency relationship here.

You indeed do have to start the process of requirements gathering before you can start designing anything.
Otherwise you're just desiging a whatever and don't even know if it has anything to do with your product. But this relationship can and should feed back on itself. So your Design process may have Design Outputs that are themselves Requirements that get fed into the Requirements Analysis process that creates the Design Inputs to begin with.

So it's an iterative thing. You do some requirements analysis and come up with some basic requirements and then you do some initial design work to come up with some architecture maybe, do some research into what some of the ramifications are, and then feed that back into requirements with your findings. Then this loops back on itself and at some point you actually start trying to implement the design, which will be changing but when you're here you know enough to start and see if your assumptions are correct. They won't be. This will feed back into design, and this may result in more requirements and these may in fact conflict with others.

At the end of this you need a correct implementation of a coherent design that responds to the requirements.

So I started out with some "Design Inputs". Standards don't say what these are so I'm borrowing a little from SysML and a little from some of the processes I saw when doing medical software development. I think maybe there should be more up-front test design than I'm doing, which was just to jot down some "acceptance criteria" but when the whole thing is done and documented those criteria I think will translate into actual tests or at least be linked to them. The object here is so that those who desire the product have thoroughly thought out what they really want and how they'll tell if they got it. The more detail the better but generally you don't get to hash it all out and that has diminishing returns on quality and coherence of design.

The Project

The Project code is here. I'd first like to discuss a couple of things I did here to help with quality. The first of these is a standard development environment that is easily installed and entered. The second is the assertion of commit checks in the form of pre-commit hooks.

For the first, I'm currently using the Nix package manager and devshells library along with a docker image to support some python utilities. The devshell setup lets me activate some commands on entry, pull in commands the developer may not currently have in their environment, and set up some aliases and commands of my own. In my case the main command I need at this time is Jupyter Book version 1 because that's what I'm using to document my project.

For the second part I'm using the previously mentioned pre-commit plugin that I install with Nix. I do expect I may run into trouble here since it's Python based and Nix doesn't play well with Python but for now it's working. I add the conventional-pre-commit plugin for it to make sure I always use Conventional Commits when I commit. Why Conventional Commits? Because what the format is isn't as important as that there is one and it's not worth thinking about too much. That standard covers pretty much everything that needs covering so there you go.

Yes, the hook has already irritated me but I'm keeping it. Using Conventional Commits will allow me to automate things like release numbering, changelog generation, etc... Having thoughtful commit comments is really important to keep an informative history. The Conventional Commit format gives you some reason to think about what the commit content is going to be and helps you with some basic things you really need to include while encouraging more. This is not something that should be forgotten about and it's going to be central to my own Quality Management System. My own comments may not be the best always, but with this in place I'm at least giving it some consideration. Have a look:

Let's see those Design Inputs

Here is the version I would have put forward as a first attempt, though there would have been more back and forth during this process with the actual client to come up with these. On my own I put on both hats a few different times.

As you'll note, there's really only one feature requirement in the entire thing: take form input and deliver to the user. The rest of the requirements are largely about the security features used to try limiting how much this thing costs me to run, how much it spams the user, and that it NEVER turns into a spam source for random people.

There was a few times when I really had a particular implementation in mind. I tried hard to discourage myself from most of these because, and this can be hard for a client to hear, how the thing does the thing isn't the important part for this process. The design process really does need the freedom to reach out and find the things that will best implement exactly what is desired, not a pre-concieved notion of what that will be. It's very difficult to do sometimes and it's not always clear you are focusing on an implementation rather than on what you actually want, but it's very worth making sure you think long and hard about it. In the end I ended up with quite a few less, much more manageable requirements that say exactly what I want done.

This is a first draft and I'm not the best at making clean documentation but it should at least be clear.

Design and planning

Next time I'll talk about the Design and Planning I've done previous to writing this blog. In the meantime I'm going to start on actual coding.

Hello Again and First Client Website

2026-08-14T00:00:00Z

I've recreated my site yet again. I removed the profile-esque front page I had for a standard introduction page. I also removed my photo and the funny stripe it had down the left for bigger screens. It's just a plain site now.

I also converted to eleventy because I'm going to start using it for website development from here on unless my client wants me to target something else. It gives me way more power and control. There's more to learn but less to fight with.

I also used stuff I learned from every layout though not a lot in this site. I used more from there at Coastal Movement Studio.

Finally, I removed the old blog articles that were just about me learning. That stuff was probably not actually useful for anyone but me. I'm not sure if I'm going to totally stop doing that kind of article, but for now I want to concentrate on other types of things for this site.

First client website

I recently published the first site I did for someone else. It went through a first iteration in which I used Hugo to generate the site. I wasn't really happy with that code and there were some changes needed to the site so I redid it in 11ty. I had also bought Every Layout and redid all of the site css using things I learned from there. Finally, to get started on 11ty I leveraged this tutorial.

Everyone is pretty happy with it as it is now. The layout works way better, especially on smaller displays that I'd had trouble getting to behave before using the techniques in Every Layout.

I had her register her own domain name that I then configured to point at her website hosted on GitLab Pages. This is a free service that hosts a static website from a git repository. This site is then configured to use Let's Encrypt to serve over https--this is important even though she's not currently selling anything or keeping peoples' information at that site.

The repository is configured to build the site any time I push changes to the main branch. The GitLab documentation on setting this all up is very well done and easy to follow so you don't need me for it, but I've done it a few times now so can be a big help making sure it gets configured correctly and yes, you can mess things up. I help people through stuff like this too though and the objective here is really to empower my clients to be able to do more on their own with reduced expenses. In theory, she can edit the content of her site any time she wants and it'll get updated and I'm not needed. This is going to require some training in things like git though, which is a developer tool but ties in with system tools and isn't THAT hard to understand--there's also a decent online editor that GitLab provides.

The cost for renewal of the domain is going to be much higher next year but still < $50 probably. So long as GitLab continues to offer this service that's the only ongoing cost required to keep the site up and it'll just stay that way as long as the domain is registered. The primary expense is in site development and changes. To have me create a site like it would cost something in the $1-2000 range and take 1-2 weeks. I work directly with you at your level so you get what you want.