From 35396d16cd248bced5057d35b7dbb495032d1716 Mon Sep 17 00:00:00 2001 From: Emil Lerch Date: Mon, 6 Sep 2021 15:57:46 -0700 Subject: [PATCH] clean up README - we are in pretty good shape for usage --- README.md | 55 ++++++++++++++++++++++++------------------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 99c190b..4e5a39a 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [![Build Status](https://drone.lerch.org/api/badges/lobo/aws-sdk-for-zig/status.svg)](https://drone.lerch.org/lobo/aws-sdk-for-zig) -Ok, so it's not actually an SDK (yet). Right now the SDK should support -any "query-based" operation and probably EC2, though this isn't tested yet. -Total service count should be around 18 services supported. If you use an -unsupported service, you'll get a compile error. +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 my first serious zig effort, so please issue a PR if the code isn't "ziggy" or if there's a better way. @@ -23,10 +25,9 @@ I am assuming here that if you're playing with zig, you pretty much know what you're doing, so I will stay brief. First, the dependencies are required. Use the Dockerfile to build these. -a `docker build` will do, but be prepared for it to run a while. Openssl in -particular will take a while, but without any particular knowledge -I'm also hoping/expecting AWS to factor out that library sometime in -the future. +a `docker build` will do, but be prepared for it to run a while. The +Dockerfile has been tested on x86_64 linux, but I do hope to get arm64 +supported as well. Once that's done, you'll have an alpine image with all dependencies ready to go and zig master installed. There are some build-related things still @@ -35,16 +36,15 @@ a standard release. * `zig build` should work. It will build the code generation project, run the code generation, then build the main project with the generated code. -* Install make and use the included Makefile. Going this path should be fine - with zig 0.8.0 release, but code generation has not been added to the - Makefile yet (ever?), so you'll be on your own for that. + 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. ## Running This library uses the aws c libraries for it's work, so it operates like most other 'AWS things'. Note that I tested by setting the appropriate environment variables, so config files haven't gotten a run through. -main.zig gives you a program to call sts GetCallerIdentity. +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 supercede all other configuration. @@ -90,29 +90,22 @@ Dockerfile in this repo will manage this TODO List: -* Implement jitter/exponential backoff. This appears to be configuration of `aws_c_io` and should therefore be trivial +* Implement jitter/exponential backoff. This appears to be configuration of + `aws_c_io` and should therefore be trivial * Implement timeouts and other TODO's in the code -* Implement error handling for 4xx, 5xx and other unexpected return values -* ✓ Implement generic response body -> Response type handling (right now, this is hard-coded) -* ✓ Implement codegen for services with xml structures (using Smithy models) -* ✓ Implement codegen for others (using Smithy models) -* Switch to aws-c-cal upstream once [PR for full static musl build support is merged](https://github.com/awslabs/aws-c-cal/pull/89) (see Dockerfile) +* Switch to aws-c-cal upstream once [PR for full static musl build support is merged](https://github.com/awslabs/aws-c-cal/pull/89) + (see Dockerfile) * Move to compiler on tagged release (hopefully 0.8.1) -(new 2021-05-29. I will proceed in this order unless I get other requests) -* ✓ Implement [AWS query protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-query-protocol.html). This is the protocol in use by sts.getcalleridentity. Total service count 18 -* ✓ Implement [AWS Json 1.0 protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-json-1_0-protocol.html). Includes dynamodb. Total service count 18 -* ✓ Implement [AWS Json 1.1 protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-json-1_1-protocol.html). Includes ecs. Total service count 105 -* Implement [AWS Rest Json 1 protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-restjson1-protocol.html). Includes lambda. Total service count 127 -* Implement [AWS restXml protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-restxml-protocol.html). Includes S3. Total service count 4. This may be blocked due to the same issue as EC2. -* Implement [AWS EC2 query protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-ec2-query-protocol.html). Includes EC2. Total service count 1. This is currently blocked, probably on self-hosted compiler coming in zig 0.9.0 (January 2022) due to compiler bug discovered. More details and llvm ir log can be found in the [XML branch](https://git.lerch.org/lobo/aws-sdk-for-zig/src/branch/xml). + (new 2021-05-29. I will proceed in this order unless I get other requests) +* Implement [AWS restXml protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-restxml-protocol.html). + Includes S3. Total service count 4. This may be blocked due to the same issue as EC2. +* Implement [AWS EC2 query protocol](https://awslabs.github.io/smithy/1.0/spec/aws/aws-ec2-query-protocol.html). + Includes EC2. Total service count 1. This is currently blocked, probably on + self-hosted compiler coming in zig 0.9.0 (January 2022) due to compiler bug + discovered. More details and llvm ir log can be found in the + [XML branch](https://git.lerch.org/lobo/aws-sdk-for-zig/src/branch/xml). Compiler wishlist/watchlist: -* ~~[Allow declarations for comptime type generation](https://github.com/ziglang/zig/issues/6709)~~ - -This is no longer as important. The primary issue was in the return value, but -due to the way AWS responses are provided, we are able to statically declare a -type and thus allow our types to be generated. - * [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)