#Tag
Today's rough plan:
...and I'm sure I missed a few steps I will only realize when I get there.
Due to popular1 demand, the nightly builds of iocaine are available from a convenient Apt repository for #Debian and Debian-based distributions!
Look here for a short install guide.
Once 3.0 is released, stable releases will appear in the same repository too, as the iocaine package (nightlies are in iocaine-nightly).
While the distribution says "unstable", the binaries are static binaries, they'll run on any Debian or Debian-derived system. They do assume systemd, however.
There's been one suggestion! But I like Debian, and it's been a while I wrote a debian/rules file without Debhelper, this was an opportunity I could not pass up. ↩︎
I've made a lot of progress finishing the last missing piece of the #iocaine3 documentation: the scripting environment reference guide.
It's not complete yet, but it's taking shape. It will be in a reasonable shape tomorrow, and #iocaine 3.0.0 will be released tomorrow1 night.
Where tomorrow, I mean after sleep. It's already Friday the 14th here. ↩︎
Wrote another batch of #iocaine3 docs: documented most of the matchers, and logging, and standard language runtime library extensions.
Some hard parts still remain, but we're inching closer.
I have about 3 hours left of the day. I shall spend it on #iocaine3 docs. I don't want to delay the 3.0 release (planned for this friday) further.
Hrm hrm. Once I'm done with #iocaine3 documentation... do I release 3.0.0-rc.3 (there were a few changes since -rc.2), or go for 3.0.0?
I think I'll go for 3.0.0 at this point.
Fixed some #iocaine3 bugs that surfaced last night while writing documentation, went to test things again, and found more bugs!
This particular bug is, again, HAProxy-related: if the incoming request has an iocaine-decision header, we mark that as garbage, and route it to the garbage-generating backend directly, skipping the decision making.
However, most of the metrics are handled during decision making, so short-circuiting that also means that metrics won't be set.
I can't do metrics in the short-circuit branch, because that has the potential of running twice.
Luckily, this was enough to persuade myself not to think about this further right now, and I successfully postponed it to another day.
Yay!
Nevertheless, some progress was made: if I end up writing this, I'll use Roto for middleware. Will have to figure out how, but this feels like the right path forward.
With that out of the way: back to #iocaine3! I've got a pull request to review, and more documentation to finish.
Today, my mind wandered off, and started thinking about a reverse proxy with first class support for #iocaine again.
This has been on my mind a lot lately, in various shapes and forms, especially since I redesigned #iocaine3's configuration, and it can spawn any number of server processes.
But I don't want to put this into iocaine itself, that'd pull in a lot of otherwise unnecessary dependencies. I could do without any, if I made it incredibly simple and limited, but... that doesn't feel right.
Today's train of thought led to an idea that I'd build it as a separate project, which would depend on iocaine, and use it as a library. It wouldn't communicate with an external iocaine like the traefik/haproxy/nginx/caddy/apache modules do (or will) - it would embed it.
I have released iocaine 3.0.0-rc.2, hopefully the last release candidate.
Compared to rc.1, the majority of changes are related to testing & debugging. The former iocaine-handler-test binary was merged into the main iocaine binary, and it's now possible to send synthethic requests to handlers, without starting up a server. One can test decision making (with iocaine test decision), and output generation (with iocaine test output).
Of course, iocaine test suite (formerly iocaine test, which still works, as it defaults to test suite) continues to function, and can run the test suite of any (or all) declared handlers. Previously, it only ran handlers used by at least one server, it was not able to run declared but unused ones.
Outside of tests & debugging improvements, the built-in request handler can now emit logs (but this is disabled by default), and ships with a recent copy of ai.robots.txt's robots.json, and is, as such, fully functional out of the box.
Oh, and Lua was made optional. Enabled by default, but if you're compiling from source, Lua can be disabled, and you save ~2MiB on binary size.
While documentation about #iocaine3 is limited, I'd appreciate any testing. Doesn't have to be deep, or thorough, just glancing over the docs, and letting me know if anything is missing would be very, very useful.
I hope to release iocaine 3.0.0 either next weekend (possible, but less likely) or the weekend after.
I've been running it onyself for a good while now, it's working great, but I'm just one person. I'm intimately familiar with it too, which means I might easily write documentation that's missing crucial information, because I think it is obvious.
Weekend plans are bearing fruit: iocaine + Caddy guide updated for iocaine 3. It's exactly the same as for 2.x, but with slightly different intro text.
This was the easy part.
Managed to convince my brain that nginx ain't that bad, so there's now an iocaine + nginx guide too. This one is hopefully more informative than what I had for 2.x.
Weekend plans: finish documenting the iocaine + your-choice-of-reverse-proxy stuff. The Caddy docs are in reasonable shape, it's pretty much the same as in 2.x.
The nginx docs need a lot of work, and I need to write traefik and haproxy docs, and have another go at Apache, see if it has any way to work with iocaine.
Weekend plans are bearing fruit: iocaine + Caddy guide updated for iocaine 3. It's exactly the same as for 2.x, but with slightly different intro text.
This was the easy part.
A couple of days later: Getting started with iocaine on NixOS.
But the hard part of the documentation journey is only just beginning.
Weekend plans: finish documenting the iocaine + your-choice-of-reverse-proxy stuff. The Caddy docs are in reasonable shape, it's pretty much the same as in 2.x.
The nginx docs need a lot of work, and I need to write traefik and haproxy docs, and have another go at Apache, see if it has any way to work with iocaine.
Now, the KDL configuration reference was nice. But sometimes we are comitting crimes indirectly! Sometimes we configure iocaine through - shock, horror! - Nix expressions.
KDL is great for humans to read and write. It's less suitable to generate from Nix expressions. Possible, sure, but other formats like JSON, YAML and TOML lend themselves better for that purpose.
Besides, iocaine is very happy to let You choose your own poison. You can even mix and match them. You can choose all of them!
So I documented the serialized formats too.
Go forth1 and multiply, lets deploy more iocaine servers!
...I should add a Forth interpreter as a supported language. For fun. ↩︎
A couple of days later: Getting started with iocaine on NixOS.
But the hard part of the documentation journey is only just beginning.
Spent way too much time writing #iocaine3 documentation last night (not published yet), tonight, I'll go to bed early.
I think I have a plan. I made great progress in documenting #iocaine3, a couple of footguns fell out, and I fixed them.
What if I made a release candidate? Not today, but on the 23rd, when I originally planned to release 3.0. At this point, any changes on main will be bugfixes and polishing, some documentation exists, so 3.0.0-rc1 sounds about right.
Continuing down the path of crime, a Getting Started with iocaine & containers guide is now public, documenting the process for the upcoming iocaine 3.0 release.
Go forth, and act maliciously!
PSA to fellow malicious actors1: I have begun publishing documentation for the upcoming iocaine 3.0 release, starting with a Getting Started guide.
How about some configuration reference?
Once we get started on the criminal path, there's no stopping us. We move fast and break thingsCrawlers.
Now, the KDL configuration reference was nice. But sometimes we are comitting crimes indirectly! Sometimes we configure iocaine through - shock, horror! - Nix expressions.
KDL is great for humans to read and write. It's less suitable to generate from Nix expressions. Possible, sure, but other formats like JSON, YAML and TOML lend themselves better for that purpose.
Besides, iocaine is very happy to let You choose your own poison. You can even mix and match them. You can choose all of them!
So I documented the serialized formats too.
Go forth1 and multiply, lets deploy more iocaine servers!
...I should add a Forth interpreter as a supported language. For fun. ↩︎
I think I spotted another bug of the bad footgun type in iocaine, this time while documenting the TOML, JSON and YAML config formats.
Looks like bind "address" unix-socket-access=group is not parsed properly when using KDL, the unix-socket-access part gets lost.
JSON, TOML, and YAML work, and the property is shown when rendering a JSON-original config into KDL. But when the original is KDL, the property is missing.
That's Bad™.
A space for Bonfire maintainers and contributors to communicate
