aws-sdk-for-zig/README.md

AWS SDK for Zig (zig-native branch)

WARNING: This branch is in development. It works, but is still brittle

This SDK currently supports all AWS services except EC2 and S3. These two services only support XML, and zig 0.8.0 and master both trigger compile errors while incorporating the XML parser. S3 also requires some plumbing tweaks in the signature calculation, which is planned for a zig version (probably self-hosted 0.9.0) that no longer has an error triggered. Examples of usage are in src/main.zig.

This is designed to be built statically using the aws_c_* libraries, so we inherit a lot of the goodness of the work going on there. Current executable size is 9.7M, about half of which is due to the SSL library. Running strip on the executable after compilation (it seems zig strip only goes so far), reduces this to 4.3M. This is for x86_linux, (which is all that's tested at the moment).

Building

zig build should work. It will build the code generation project, run the code generation, then build the main project with the generated code. There is also a Makefile included, but this hasn't been used in a while and I'm not sure that works at the moment.

First time build should use zig build -Dfetch to fetch dependent packages (zfetch and friends).

Running

This library mimics the aws c libraries for it's work, so it operates like most other 'AWS things'. main.zig gives you a handful of examples for working with services. For local testing or alternative endpoints, there's no real standard, so there is code to look for AWS_ENDPOINT_URL environment variable that will supersede all other configuration.

Limitations

There are many nuances of AWS V4 signature calculation. S3 is not supported because it uses many of these test cases. STS tokens using a session token are not yet implemented, though should be trivial. I have also seen a few service errors caused by discrepancies in signatures, though I don't know yet if this was an issue in the service itself (has not repro'd) or if there is a latent bug.

Only environment variable based credentials can be used at the moment.

TODO List:

• Fix failure on rest_json_1_work_with_lambda test
• Add certificate verification
• Add STS key support
• Implement credentials provider
• Implement jitter/exponential backoff
• Implement timeouts and other TODO's in the code
• Implement AWS restXml protocol. Includes S3. Total service count 4. This may be blocked due to the same issue as EC2.
• Implement AWS EC2 query protocol. Includes EC2. Total service count 1. This may be blocked on a compiler bug, though has not been tested with zig 0.9.0. It may need to wait for zig 0.10.0 when self-hosted compiler is likely to be completed (zig 0.10.0 eta May 2022) discovered. More details and llvm ir log can be found in the XML branch.
• Implement sigv4a signing

Compiler wishlist/watchlist:

• Merge PR to allow stripping -static
• comptime allocations so we can read files, etc (or is there another way)