logo

smithy4rs

Smithy code generators for Rust

Build Status License crates.io dependencies

smithy4rs provides Smithy code generators for clients, server, and shapes for the Rust programming language.

Generated code supports protocol-agnostic clients, servers, and event systems via schema-guided (de)serialization where schema metadata is made available at runtime.

Info

smithy4rs is an unofficial, community-supported Smithy code generator for Rust.

If you are looking for the official code generators used to create the the AWS Rust SDK, head over to smithy-rs.

Core components

smithy4rs contains three core types of components:

  1. smithy-build plugins - used to integrate with the smithy toolchain and generate code from a Smithy model.
  2. Core libraries - provide the core functionality for generated Rust code.
  3. Protocol implementations - libraries that implement (de)serialization and binding logic that can be used to interface between clients and servers.

Early Access

All interfaces of code generators, core libraries, and protocol implementations are unstable and may be subject to change without notice or guaranteed of backwards-compatibility.

Getting Started

For a guided introduction to this project, see the Quick Start guide.

For a more in-depth exploration, check out our Tutorials.

FAQ

What is different between smithy4rs and the official code generators?

The official AWS rust code generators create "model ignorant" code. No schema metadata is available at runtime and (de)serialization code is generated on a per-protocol basis. This approach can lead to fast (de)serialization at the expense of extensibility/flexibility.

In contrast, smithy4rs generates "schema-aware" code. Schema metadata is made available to (de)serializers and schemas can even be created and used dynamically at runtime. The flexibility of this approach allows smithy4rs to support a number of features that the AWS Rust code generators do not:

  1. serde compatibility - smithy4rs allows users to optionally (de)serialize shapes using the rust serde ecosystem. See serde-compatibility for more info on how to enable this feature.
  2. Type codegen - smithy4rs allows users to generate standalone types without need for a client or service. This makes the development of more flexible middleware possible for clients and servers and even opens up the possibility of generating event types.
  3. Protocol-agnosticism - The shapes, clients, and servers generated by smithy4rs are fully protocol-agnostic. In contrast, smithy-rs generates protocol-specific (de)serialization code.
  4. Dynamic schemas - smithy4rs is designed to allow users to dynamically load and use schemas for (de)serialization. This can be used to support fully dynamic clients and server-mocks.
  5. "Any"-ish Document support - smithy-java introduced a concept of documents as an Any type for the Smithy data model. smithy4rs provides first class support for this new Document model.

What does it mean to be "protocol agnostic"?

A "protocol" is composed of both the transport (i.e. HTTP or MQTT) and serialization format (i.e. JSON or XML) used to communicate data between clients and servers.

Data representations in the Smithy IDL are not tied to any specific wire format or transport. In contrast to IDL's like protobuf (gRPC), this allows Smithy servers and clients to support any protocol they would like, even swapping out client protocols at runtime.

This ability to be "agnostic" to the final wire format and transport is what is meant when we say Smithy is "protocol-agnostic".