If you think these unit tests look crappy, that's because they are.
Actual behavioral tests are pretty much exclusively relying on the
underlying C library being well-tested, so all these tests are really
trying to do is ref the bindings in our endpoints to make sure there
aren't any compilation issues with them. Obviously this is making a
difference, since a variety of issues have been found and addressed as
a result.
Since I went to the effort of getting this to build with LibreSSL, it
makes sense to check that it works. And it seems to. There's nothing
special about the certificates added, except that they don't expire
for 100 years, which is hopefully long enough that nothing will matter
any more. They get baked into the test executable, since this was the
best way I could figure out to be able to consistently load them
during runtime, since they're stored relative to the source, not
necessarily relative to the working directory in use when the test
executable is run.
This required some augmentation to the test server launcher which will
make it easier to add additional flags to it in the future, if that
becomes necessary.
Tests are CC0/public domain because there's no reason for them not to
be. Examples are also CC0/public domain, but this may be a little bit
weird because they are largely straightforward ports of examples from
nats.c which carry the Apache license. However, I personally wrote
them against the zig bindings and I doubt anyone will end up in a
court of law due to their software containing uselessly trivial
example code.
Various copypasta and typing errors around the thunks, some other
copypasta errors, etc. Also add a test which hits a decent chunk of
the API surface of ConnectionOptions, which is how these issues were
caught in the first place. This is an ugly test, but it has clearly
served its purpose.
This is probably the sort of thing that I wouldn't actually think of
having explicit test coverage for if I hadn't accidentally ran across
it while fiddling. I will compensate for this easily by not actually
writing tests at all.
After contemplating this for a little bit, there's no point in exposing
these separately from the plain variants. Even nats.c internally calls
its plain variants after calling `strlen` on the input. Zig benefits
from having nicer pointer types than C, so we get "string" handling
for free from the fact that the standard variants take slices anyway.
I believe the standard API surface is now completely wrapped, ignoring
whatever cool copy-paste errors or other mistakes I introduced which
are currently undetectable due to lazy analysis and lack of test
coverage. Cool.
This was kind of tedious, but there were some interesting choices to be
made with regards to how the callback signatures should be adapted,
especially in the few cases that heavily use out-params in C. Ignoring
the lack of test coverage, this puts us pretty close to having the
entire basic API wrapped.
There are a several options that set up callbacks that I did not wrap
in this first pass because I need to decide on whether or not it makes
sense to move the various thunks into a common location. There's one
that could be shared between the subscriptions and here due to having
the same signature, but I'm not sure there are any others that would
really benefit from cross-file sharing.
This is pretty much just the API surface that is used in the demo code
for now, with a couple of minor things I tacked on while getting a
feel for how I was going to go about it. Unfortunately, the diff is
too messy to show the improvement provided by the wrapped API, but I'm
pretty pleased with how it is turning out so far. In general, there
have been no major hiccups.
Most of the time working on this was spent noodling about how to create
the subscription callback thunk to provide type safety and pointer
nullability guarantees for the subscription zig API. I'm satisfied
with the solution in place now: it seems to have good default
ergonomics and very few downsides except that the callback function
must be known at compile time. An earlier iteration of this code
supported runtime function pointers but had a showstopping problem
with memory management. In order to store the runtime callback
pointer, the thunk would need to be allocated, but there was no way of
attaching our allocated memory to the c-library subscription object.
No attachment meant that there were a number of error scenarios where
the allocated thunk couldn't be freed correctly.
Ultimately, if the user needs to use runtime callback pointers they can
write a comptime known callback that calls a runtime known callback.
This way all of the object lifetime and ownership is in the user's
hands, which is really where it needs to belong anyway for this.
