torque dfb6d10277
connection: add additional tests and fix various bindings
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.
2023-09-02 21:56:40 -07:00
2023-08-15 00:16:05 -07:00
2023-08-14 00:29:34 -07:00

NATS - Zig Client

This is a Zig client library for the NATS messaging system. It's currently a thin wrapper over NATS.c.

There are three main goals:

  1. Provide a Zig package that can be used with the Zig package manager.
  2. Provide a native-feeling Zig client API.
  3. Support cross-compilation to the platforms that Zig supports.

Right now, in service of goal 3, the underlying C library is built without certain features (notably, without streaming support) due to those features requiring managing some transitive dependencies (for streaming, the protobuf-c library). Solving this limitation is somewhere on the roadmap, but it's not high priority. nats.c is compiled against a copy of LibreSSL that has been wrapped with the zig build system. This appears to work, but it notably is not specifically OpenSSL, so there may be corner cases around encrypted connections.

Zig Version Support

Since the language is still under active development, any written Zig code is a moving target. The plan is to support Zig 0.11.* exclusively until the NATS library API has good coverage and is stabilized. At that point, if there are major breaking changes, a maintenance branch will be created, and master will probably move to track Zig master.

Using

NATS.zig is ready-to-use with the Zig package manager. With Zig 0.11.x, this means you will need to create a build.zig.zon and modify your build.zig to use the dependency.

Example build.zig.zon

.{
    .name = "my cool project",
    .version = "0.1.0",
    .dependencies = .{
        .nats = .{
            .url = "https://github.com/epicyclic-dev/nats.zig/archive/<git commit hash>.tar.gz",
            // on first run, `zig build` will prompt you to add the missing hash.
            // .hash = "",
        },
    },
}

Example build.zig

const std = @import("std");

pub fn build(b: *std.Build) void {
    const my_program = b.addExecutable(.{
        .name="cool-project",
        .root_source_file = .{.path = "my_cool_project.zig"},
    });

    my_program.addModule(
        "nats",
        b.dependency("nats", .{}).module("nats"),
    );

    b.installArtifact(my_program);
}

Building

Some basic example executables can be built using zig build examples. These examples expect you to be running a copy of nats-server listening for unencrypted connections on localhost:4222 (the default NATS port).

Testing

Unit tests can be run using zig build test. The unit tests expect an executable named nats-server to be in your PATH in order to run properly.

License

Unless noted otherwise (check file headers), all source code is licensed under the Apache License, Version 2.0 (which is also the nats.c license).

Licensed under the Apache License, Version 2.0 (the "License");
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Description
nats client for zig (currently a wrapper around nats.c)
Readme 3 MiB
Languages
Zig 99.3%
Shell 0.7%