aws-sdk-for-zig/README.md

202 lines
6.5 KiB
Markdown
Raw Normal View History

AWS SDK for Zig
===============
2021-04-27 18:24:01 +00:00
2024-01-22 22:26:10 +00:00
[![Build Status: Zig 0.12.0-dev.2063+804cee3b9](https://actions-status.lerch.org/lobo/aws-sdk-for-zig/zig-mach)](https://git.lerch.org/lobo/aws-sdk-for-zig/actions?workflow=zig-mach.yaml&state=closed)
[![Build Status: Zig Nightly](https://actions-status.lerch.org/lobo/aws-sdk-for-zig/zig-nightly)](https://git.lerch.org/lobo/aws-sdk-for-zig/actions?workflow=zig-nightly.yaml&state=closed)
2022-01-11 19:19:40 +00:00
**NOTE: THIS SDK IS CURRENTLY UNUSABLE FOR SEVERAL IMPORTANT AWS SERVICES
WITHOUT A PROXY. SEE LIMITATIONS SECTION BELOW**
2023-08-27 19:12:04 +00:00
Current executable size for the demo is 980k after compiling with -Doptimize=ReleaseSmall
in 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
2024-01-22 22:26:10 +00:00
Zig-Develop Branch
------------------
This branch is intended for use with the in-development version of Zig. This
starts with 0.12.0-dev.2150+63de8a598. I will try to keep this branch up to date
with latest, but with a special eye towards aligning with [Mach Engine's Nominated
Zig Versions](https://machengine.org/about/nominated-zig/). As nightly zig versions
disappear off the downloads page (and back end server), we can use the mirroring
that the Mach Engine participates in to pull these versions.
Building
--------
2021-04-27 18:24:01 +00:00
2023-08-27 19:12:04 +00:00
`zig build` should work. It will build the code generation project, fetch model
files from upstream AWS Go SDK v2, run the code generation, then build the main
project with the generated code. Testing can be done with `zig test`.
Using
-----
2021-04-27 18:24:01 +00:00
2023-08-27 19:12:04 +00:00
This is designed for use with the Zig 0.11 package manager, and exposes a module
called "aws". Set up `build.zig.zon` and add the dependency/module to your project
2023-09-06 01:30:42 +00:00
as normal and the package manager should do its thing. A full example can be found
in [/example](example/README.md).
2021-04-27 18:24:01 +00:00
2023-09-06 01:30:42 +00:00
Configuring the module and/or Running the demo
----------------------------------------------
2021-04-27 18:24:01 +00:00
2022-01-11 19:19:40 +00:00
This library mimics the aws c libraries for it's work, so it operates like most
2023-09-06 01:30:42 +00:00
other 'AWS things'. [/src/main.zig](src/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.
Other branches
--------------
The default branch is fully functional but requires TLS 1.3. Until AWS Services
support TLS 1.3 at the end of 2023, the [0.9.0 branch](https://git.lerch.org/lobo/aws-sdk-for-zig/src/branch/0.9.0)
may be of use. More details below in limitations. This branch overall is
superior, as is the 0.11 compiler, but if you need a service that doesn't support
TLS 1.3 and you need it right away, feel free to use that branch. Note I do not
intend to update code in the 0.9.0 branch, but will accept PRs.
2022-01-20 15:41:35 +00:00
2023-08-27 19:12:04 +00:00
An [old branch based on aws-crt](https://github.com/elerch/aws-sdk-for-zig/tree/aws-crt) exists
for posterity, and supports x86_64 linux. The old branch is deprecated, so if
there are issues you see that work correctly in the aws-crt branch, please
2023-09-06 01:30:42 +00:00
file an issue. I can't think of a reason to use this branch any more. I do not
intend to entertain PRs on this branch, but reach out if you think it is important.
2021-04-27 18:24:01 +00:00
Limitations
-----------
2022-01-20 03:37:17 +00:00
The zig 0.11 HTTP client supports TLS 1.3 only. This, IMHO, is a reasonable
restriction given its introduction 5 years ago, but is inflicting some short
term pain on this project as AWS has not yet fully implemented the protocol. AWS has
committed to [TLS 1.3 support across all services by the end of 2023](https://aws.amazon.com/blogs/security/faster-aws-cloud-connections-with-tls-1-3/), but many (most) services as of August 28th have not yet
2023-08-29 22:22:13 +00:00
been upgraded. Proxy support has been added, so to get to the services that
do not yet support TLS 1.3, you can use something like [mitmproxy](https://mitmproxy.org/)
to proxy those requests. Of course, this is not a good production solution...
2022-06-29 16:24:16 +00:00
WebIdentityToken is not yet implemented.
2022-01-20 03:37:17 +00:00
2021-04-27 18:24:01 +00:00
TODO List:
2023-08-27 19:12:04 +00:00
* Json parsing is based on a fork of the 0.9.0 (maybe earlier?) json parser.
This needs a re-visit. Note also that a json.zig file is embedded/copied
from the codegen project, so that also needs a second look.
2023-08-27 19:12:04 +00:00
* Take a look to see about compilation speed. With codegen caching this is
reasonable, but still takes longer than needed.
* Upgrade the model files. This is a simple tasks, but I'd like the first
item on this list to be completed first.
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:
* [comptime allocations](https://github.com/ziglang/zig/issues/1291) so we can read files, etc (or is there another way)
2023-09-06 01:30:42 +00:00
Services without TLS 1.3 support (46 services out of 255 total)
---------------------------------------------------------------
2023-09-06 01:30:42 +00:00
NOTE THAT EC2, S3, Lambda, DynamoDB, SNS, SQS are all part of this list!!
2023-09-06 01:30:42 +00:00
```
2024-01-08 21:43:07 +00:00
cloudsearch
2023-09-06 01:30:42 +00:00
codecommit
codestar
cognito-identity
cognito-idp
cognito-sync
2024-01-08 21:43:07 +00:00
data.iot
data.jobs.iot
2023-09-06 01:30:42 +00:00
dax
2024-01-08 21:43:07 +00:00
discovery
2023-09-06 01:30:42 +00:00
dynamodb
ec2
elasticache
elasticbeanstalk
elasticloadbalancing
2024-01-08 21:43:07 +00:00
featurestore-runtime.sagemaker
glacier
ingest.timestream
2023-09-06 01:30:42 +00:00
iotsitewise
kinesis
kinesisvideo
lambda
2024-01-08 21:43:07 +00:00
logs
2023-09-06 01:30:42 +00:00
models.lex
2024-01-08 21:43:07 +00:00
monitoring
oidc
2023-09-06 01:30:42 +00:00
opsworks
personalize-events
personalize-runtime
2024-01-08 21:43:07 +00:00
portal.sso
query.timestream
2023-09-06 01:30:42 +00:00
redshift
2024-01-08 21:43:07 +00:00
runtime.lex
2023-09-06 01:30:42 +00:00
runtime.sagemaker
2024-01-08 21:43:07 +00:00
runtime-v2-lex
s3
2023-09-06 01:30:42 +00:00
sns
sqs
sso
2024-01-08 21:43:07 +00:00
streams.dynamodb
2023-09-06 01:30:42 +00:00
sts
support
wafv2
```
2023-09-14 21:05:35 +00:00
Dependency tree
---------------
No dependencies:
* aws_authentication: base structure for credentials (only one type)
* aws_http_base: contains basic structures for http requests/results
* case: provides functions to change casing
* date: provides limited date manipulation functions
* http_client_17015_issue: zig 0.11 http client, with changes
* json: custom version of earlier stdlib json parser
* xml: custom xml parser library
* url: custom url encoding
aws_credentials: Allows credential handling
aws_authentication
aws_http:
http_client_17015_issue
aws_http_base
aws_signing
aws_signing: handles signing of http requests
aws_http_base
aws_authentication
date
aws: main usage point for libraries
aws_http
json
url
case
date
servicemodel
xml_shaper
aws_credentials
aws_authentication
main: main entrypoint for demo executable
aws
servicemodel: Provides access to all aws service generated models
all generated model files
xml_shaper: Manages interface from xml to in memory structures
xml
date