aws-sdk-for-zig/README.md

64 lines
2.6 KiB
Markdown
Raw Normal View History

# AWS SDK for Zig
2021-04-27 18:24:01 +00:00
2022-01-20 15:47:14 +00:00
[![Build Status](https://drone.lerch.org/api/badges/lobo/aws-sdk-for-zig/status.svg?ref=refs/heads/master)](https://drone.lerch.org/api/badges/lobo/aws-sdk-for-zig/)
2022-01-11 19:19:40 +00:00
This SDK currently supports all AWS services. restXml protocol support (4
services including S3), is still new, with lots of gaps. See TODO list below.
2021-04-27 18:24:01 +00:00
Current executable size for the demo is 1.7M (90k of which is the AWS PEM file,
2022-02-16 22:14:54 +00:00
and approximately 600K for XML services) after compiling with -Drelease-safe and
2022-01-20 20:18:47 +00:00
[stripping the executable after compilation](https://github.com/ziglang/zig/issues/351).
2022-02-16 22:14:54 +00:00
This is for x86_linux, and will vary based on services used. Tested targets:
2022-01-20 20:18:47 +00:00
* x86_64-linux
* riscv64-linux
* aarch64-linux
2022-01-20 20:31:45 +00:00
* x86_64-windows
2022-01-20 20:18:47 +00:00
* arm-linux
2022-02-09 06:36:36 +00:00
* aarch64-macos
* x86_64-macos
2021-04-27 18:24:01 +00:00
2022-02-09 06:36:36 +00:00
Tested targets are built, but not continuously tested, by CI.
2022-01-20 20:31:45 +00:00
2021-04-27 18:24:01 +00:00
## Building
2022-01-11 19:19:40 +00:00
`zig build` should work. It will build the code generation project, run
the code generation, then build the main project with the generated code.
2021-04-27 18:24:01 +00:00
2022-01-11 19:19:40 +00:00
First time build should use `zig build -Dfetch` to fetch dependent packages
(zfetch and friends).
2021-04-27 18:24:01 +00:00
## Running
2022-01-11 19:19:40 +00:00
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.
2021-04-27 18:24:01 +00:00
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
2022-01-20 15:41:35 +00:00
supersede all other configuration. Note that an alternative endpoint may
require passing in a client option to specify an different TLS root certificate
(pass null to disable certificate verification).
2022-02-10 23:29:51 +00:00
The [old branch](https://github.com/elerch/aws-sdk-for-zig/tree/aws-crt) exists
2022-02-16 22:14:54 +00:00
for posterity, and supports x86_64 linux. The old branch is deprecated.
2021-04-27 18:24:01 +00:00
2022-01-20 03:37:17 +00:00
## Limitations
There are many nuances of AWS V4 signature calculation. Parts of S3 are not supported
2022-02-10 23:29:51 +00:00
because it uses many of these test cases. WebIdentityToken is not yet
implemented.
2022-01-20 03:37:17 +00:00
2021-04-27 18:24:01 +00:00
TODO List:
* Complete development of [AWS restXml protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-restxml-protocol.html).
2022-02-16 22:14:54 +00:00
Includes S3. Total service count 4.
* Bump to zig 0.9.1. iguanaTLS, used in zFetch is still [working out 0.9.1 issues](https://github.com/alexnask/iguanaTLS/pull/29)
2022-01-11 19:19:40 +00:00
* Implement sigv4a signing
2022-02-10 17:45:18 +00:00
* Implement jitter/exponential backoff
* Implement timeouts and other TODO's in the code
* Add option to cache signature keys
2021-04-27 18:24:01 +00:00
Compiler wishlist/watchlist:
* [Merge PR to allow stripping -static](https://github.com/ziglang/zig/pull/8248)
* [comptime allocations](https://github.com/ziglang/zig/issues/1291) so we can read files, etc (or is there another way)