Tags: evopen/zap
Tags
__Introducing: zap.Router__ Thanks to StringNick, we now have `zap.Router` with handler closures support! See the `simple_router` example. `zap.Router` is missing doc comments, so if anyone wants to step up, please feel free to send a PR against the `zig-0.12.0` my way. BTW: Documentation (built on zig-0.12.0 branch) is now live at: <https://zigzap.org/zap> Doc update PRs are welcome. I am especially excited about the _guides_ feature: <https://zigzap.org/zap/#G;> __**Introduced:**__ - `zap.Router`: the router itself - `zap.RequestHandler : a nice way to capture "self" pointers of containers of request functions. - `simple_router`: example demonstrating the above Thanks again to StringNick! I updated the zig-0.12.0 branch, too, as with all recent and future releases.
__Breaking API Cleanup__ **Documentation (built on zig-0.12.0 branch) is now live at: <https://zigzap.org/zap>** Doc update PRs are welcome. I am especially excited about the _guides_ feature: <https://zigzap.org/zap/#G;> So, I spent a few days with a first pass of cleaning up Zap's API, informed by using it in production for over half a year now. **__Refactored:__** - no more type names starting with `Simple`. - zap.SimpleEndpoint -> zap.Endpoint - zap.SimpleRequest -> zap.Request - zap.SimpleHttpListener -> zap.HttpListener - ... - zap.Endpoint : zap.Endpoint, zap.Endpoint.Authenticating - zap.Endpoint.Listener.register() // was: zap.EndpointListener.addEndpoint - zap.Auth : zap.Auth.Basic, zap.Auth.BearerSingle, ... - zap.Mustache : stayed the same - zap.Request : refactored into its own file, along with supporting types and functions (e.g. http params related) - added setContentTypeFromFilename thx @hauleth. - zap.Middleware: no more MixContexts - (zig structs are fine) - check example - zap.fio : facilio C FFI stuff does not pollute zap namespace anymore - it is still available via `zap.fio`. - allocators are always first-ish param: either first or after self - more docstrings All examples and tests have been updated. Also, check out the documentation (work in progress).
__-Dopenssl is back && breaking mustache changes__ Thanks to @Vemahk, `-Dopenssl=true` is back! Apparently, while trying to pass user-defined options from a dependent project to zap, I typoed the working solution, and several people pointed out to me that it's as simple as: ```zig const zap = b.dependency("zap", .{ .target = target, .optimize = optimize, .openssl = false, // set to true to enable TLS support }); ``` As a result, we re-introduced `-Dopenssl`, use it if present, and fall back to the `ZAP_USE_OPENSSL` env var (set to `true` to enable) if not. Aaand: thanks to @chooky (BrookJeynes on GH), we have a new, clean, zig-iomatic, documented Mustache API in Zap now: ```zig var mustache = try Mustache.fromData("{{some_item}} {{& nested.item }}"); defer mustache.deinit(); const b = mustache.build(.{ .some_item = 42, .nested = .{ .item = 69, }, }); defer b.deinit(); if(b.str()) |s| { std.debug.print("{s}", .{s}); }; ``` Checkout mustache.zig and the mustache example to learn more.
__TLS / HTTPS / openssl build change!!!__
Previously, zap required `-Dopenssl=true` to build openssl support. Turns out, for projects using zap, it's insanely hard if not impossible to pass the user provided option `openssl=true` down to the zap dependency.
As a workaround, I changed the build so that it now expects an environment variable `ZAP_USE_OPENSSL` be set to `true`.
So, to build the _https_ example, run:
`ZAP_USE_OPENSSL=true zig build run-https`
*The Example*
Create the certificate and key file:
```console
$ openssl req -x509 -nodes -days 365 -sha256 -newkey rsa:2048 -keyout mykey.pem -out mycert.pem
```
Build / run the example
```console
$ ZAP_USE_OPENSSL=true zig build https
$ ZAP_USE_OPENSSL=true zig build -Dopenssl=true run-https
```
Issue an HTTPS request:
```console
$ curl -v -k https://localhost:4443/build.zig
```
Using openssl in your code is super simple:
```zig
const tls = zap.fio_tls_new(
"localhost:4443",
CERT_FILE,
KEY_FILE,
null, // key file is not password-protected
);
defer tls.deinit();
```
That `tls` data is then passed to the `SimpleHttpListener`:
```zig
var listener = zap.SimpleHttpListener.init(.{
.port = 4443,
.on_request = on_request_verbose,
.log = true,
.max_clients = 100000,
.tls = tls, // <----- h e r e
});
try listener.listen();
```
__Community PR update: HTTP options support!__ Hey, things are moving rapidly in ZAP land these days. StringNick (on GitHub) provided a PR adding HTTP options support! Many thanks for the great PR! BTW: New stuff is cooking in the 0.12.0 branch. Check out @chooky 's new mustache ;-). Maybe even in the API docs? (`zig build run-docserver` is your friend)
__Community PR update: HTTP options support!__ Hey, things are moving rapidly in ZAP land these days. StringNick (on GitHub) provided a PR adding HTTP options support! Many thanks for the great PR! BTW: New stuff is cooking in the 0.12.0 branch. Check out @chooky 's new mustache ;-). Maybe even in the API docs? (`zig build run-docserver` is your friend)
__Refactored zap.Tls__
I refactored `zap.Tls` to make it more zig-like:
```zig
// this is more zig-like:
const tls = try zap.Tls.init(.{
.server_name = "localhost:4443",
.public_certificate_file = CERT_FILE,
.private_key_file = KEY_FILE,
});
// this, too
defer tls.deinit();
var listener = zap.SimpleHttpListener.init(.{
.port = 4443,
.on_request = on_request_verbose,
.log = true,
.max_clients = 100000,
.tls = tls,
});
try listener.listen();
```
More dangerous refactorings are going to happen in the zig-0.12.0 branch, and being back-ported to master if it makes sense.
__TLS / HTTPS / openssl support!!!__
Thanks to @ColaNova's (GitHub) work, Zap can now utilize facil.io's openssl support.
In the README, at the bottom of the list of examples, there is now a super simple `https` example.
It's super simple:
```zig
const tls = zap.fio_tls_new(
"localhost:4443",
CERT_FILE,
KEY_FILE,
null, // key file is not password-protected
);
```
That `tls` data is then passed to the `SimpleHttpListener`.
The example **requires `-Dopenssl=true` on the command line**. This is so that zap doesn't depend on openssl unconditionally.
Here's what happened:
openssl in facil.io
====================
fio patches from https://github.com/CoalNova/facil.io 0.7.6-zapped branch:
* b0a7b00b - (HEAD -> 0.7.6-zapdate, coalnova/0.7.6-zapdate) Update to description (7 weeks ago) <coalnova>
* 115d07d6 - Update to delocalize OpenSSL lines (7 weeks ago) <coalnova>
* 73619a8b - Update to organize build options for TLS (7 weeks ago) <coalnova>
* 16024c0d - Update to build settings (7 weeks ago) <coalnova>
* c487bb00 - Update to fix to library name (7 weeks ago) <coalnova>
* a87818fc - Update to flag HAVE_OPENSSL as build feature (8 weeks ago) <coalnova>
* 968993b4 - Update to co/remove TODO: delete me! (8 weeks ago) <coalnova>
* 094ac99d - Update to differentiate exitcodes in TLS functions (8 weeks ago) <coalnova>
* 6d22411a - Update to expose both sets of tls functions (8 weeks ago) <coalnova>
* 007f7b19 - Update switched fio_tls_missing to fio_tls_openssl (9 weeks ago) <coalnova>
* 026c92fc - Update to expose TLS C and Header files. (9 weeks ago) <coalnova>
Changes to CoalNova's approach
------------------------------
**!Important!:** @CoalNova commented out one `#if HAVE_OPENSSL` in the C code. I will not do that as the `build.zig` will set this flag anyway. If the flag isn't specified, facil.io will compile like it did before the introduction of zap's OpenSSL support.
Addition: I had to replace the `#if HAVE_OPENSSL` in question to `#ifdef HAVE_OPENSSL` or else clang would complain. Maybe this error was the motivation for @CoalNova to remove the `#if`.
Also, since we don't install headers of facil.io anymore (as zap is the only consumer), I skipped installing facil.io's tls headers.
Changes to zap
==============
Basically 2 patches:
- [Update to include basic TLS functions](https://github.com/CoalNova/zap/commit/124a3134ca71bf41635320c0bc3c098a65aba931.patch)
- [Update to expose further functions for TLS/SSL](https://github.com/CoalNova/zap/commit/14b05451989ec66e84feae9b8efc52e4f8bed1e8.patch)
Used those but skipped the build.zig.zon stuff.
OpenSSL needs to be hidden behind a custom build option orelse all projects that depend on zap will also depend on a working openssl + libcrypto dev setup: having headers and lib installed on the system.
- [x] make openssl a build option: -Dopenssl=true
The Example
===========
Trying out openssl from the commandline first
---------------------------------------------
Trying stuff from [the command line](https://help.mulesoft.com/s/article/How-to-set-up-a-minimal-SSL-TLS-server-from-the-command-line) first.
Creating the certificate and key file:
```console
$ openssl req -x509 -nodes -days 365 -sha256 -newkey rsa:2048 -keyout mykey.pem -out mycert.pem
```
Serving the current dir:
```console
$ openssl s_server -accept 4443 -cert mycert.pem -key mykey.pem -WWW
```
Issuing an HTTPS request:
```console
$ curl -v -k https://localhost:4443/build.zig
```
The zap https example
---------------------
```console
$ zig build -Dopenssl=true https
$ zig build -Dopenssl=true run-https
```
It's super simple:
```zig
const tls = zap.fio_tls_new(
"localhost:4443",
CERT_FILE,
KEY_FILE,
null, // key file is not password-protected
);
```
That `tls` data is then passed to the `SimpleHttpListener`.
PreviousNext