AWS SDK for Zig =============== [![Build Status](https://actions-status.lerch.org/lobo/aws-sdk-for-zig/build)](https://git.lerch.org/lobo/aws-sdk-for-zig/actions?workflow=build.yaml&state=closed) **NOTE: THIS SDK IS ONLY CURRENTLY USABLE FOR A SMALL SUBSET OF AWS SERVICES WITHOUT A PROXY. SEE LIMITATIONS SECTION BELOW** 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: * x86_64-linux * riscv64-linux * aarch64-linux * x86_64-windows * arm-linux * aarch64-macos * x86_64-macos Tested targets are built, but not continuously tested, by CI. Building -------- `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 ----- 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 as normal and the package manager should do its thing. A full example can be found in [/example](example/README.md). Configuring the module and/or Running the demo ---------------------------------------------- This library mimics the aws c libraries for it's work, so it operates like most 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. 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 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. Limitations ----------- 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 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... WebIdentityToken is not yet implemented. TODO List: * 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. * 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. * Implement sigv4a signing * Implement jitter/exponential backoff * Implement timeouts and other TODO's in the code * Add option to cache signature keys Compiler wishlist/watchlist: * [comptime allocations](https://github.com/ziglang/zig/issues/1291) so we can read files, etc (or is there another way) Services with TLS 1.3 Support (116 services) -------------------------------------------- ``` acm amplify apigateway apigateway appconfig application-autoscaling applicationinsights appmesh apprunner appstream2 appsync athena backup batch cloud9 clouddirectory cloudformation cloudhsmv2 cloudsearch cloudtrail events codeartifact codebuild codedeploy codeguru-profiler codepipeline codestar-connections comprehend comprehendmedical compute-optimizer dms databrew dataexchange datasync devicefarm directconnect ds ec2-instance-connect api.ecr api.ecr-public ecs elasticfilesystem es elastictranscoder elasticmapreduce events finspace finspace-api fms frauddetector fsx gamelift glacier globalaccelerator glue healthlake honeycode identitystore inspector iot iotanalytics iotevents data.iotevents api.iotwireless ivs kafka kendra kinesisanalytics kms lakeformation license-manager lookoutvision metering.marketplace mediaconnect medialive mediapackage-vod mediastore mgh network-firewall networkmanager opsworks-cm personalize pinpoint email sms-voice.pinpoint polly qldb session.qldb quicksight rds-data redshift-data rekognition tagging route53resolver s3-outposts api.sagemaker edge.sagemaker secretsmanager servicecatalog servicediscovery servicequotas email states snowball ssm-contacts swf textract transcribe transfer translate waf-regional workdocs workmail workmailmessageflow workspaces xray ``` Services without TLS 1.3 support (139 services) ----------------------------------------------- ``` access-analyzer acm-pca amplifybackend execute-api appflow app-integrations application-cost-profiler discovery auditmanager autoscaling autoscaling-plans budgets chime cloudfront cloudsearchdomain monitoring logs codecommit codeguru-reviewer codestar codestar-notifications cognito-identity cognito-idp cognito-sync config connect contact-lens participant.connect ce profile datapipeline dax api.detective devops-guru dlm dynamodb streams.dynamodb ebs ec2 eks elasticache elasticbeanstalk api.elastic-inference elasticloadbalancing emr-containers firehose fis forecast forecastquery greengrass groundstation guardduty health iam imagebuilder devices.iot1click projects.iot1click data.iot api.iotdeviceadvisor api.fleethub.iot data.jobs.iot api.tunneling.iot iotsitewise iotthingsgraph kinesis kinesisvideo lambda models.lex models-v2-lex runtime.lex runtime-v2-lex lightsail geo lookoutequipment lookoutmetrics machinelearning macie macie2 managedblockchain catalog.marketplace marketplacecommerceanalytics entitlement.marketplace mediaconvert mediapackage data.mediastore api.mediatailor PlaybackEndpointPrefix mgn migrationhub-config mobile mq mturk-requester airflow rds nimble opsworks organizations outposts personalize-events personalize-runtime pi api.pricing ram rds redshift resource-groups robomaker route53 route53domains s3 s3-control a2i-runtime.sagemaker featurestore-runtime.sagemaker runtime.sagemaker savingsplans schemas securityhub serverlessrepo servicecatalog-appregistry shield signer sms sns sqs ssm ssm-incidents portal.sso sso oidc storagegateway sts support synthetics query.timestream ingest.timestream waf wafv2 wellarchitected worklink ``` 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