406 lines
8.2 KiB
Markdown
406 lines
8.2 KiB
Markdown
AWS SDK for Zig
|
|
===============
|
|
|
|
[](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
|