repository·series/0.19·Indexed 19 days ago
https://github.com/disneystreaming/smithy4sA Scala toolset for working with Smithy models, focused on code generation and model manipulation. It includes a CLI for generating Scala code and OpenAPI specifications, a core library providing Blob and Document types for binary and structured data, and support for executing AWS service calls via the AwsCall trait.
Smithy4s is a code generation tool that transforms Smithy interface definition language (IDL) specifications into protocol-agnostic Scala code. It is designed to be third-party-free and supports both Smithy 1.0 and Smithy 2.0 models.
Key use cases include:
The SimpleRestJson protocol is a custom Json-in/Json-out protocol for Smithy services. It uses jsoniter-scala for (de)serialization of HTTP bodies.
Semantics:
@mediaType trait is ignored; all bodies are serialized as JSON.Smithy4s provides an opt-in http4s-specific module to quickly derive HTTP services and clients using this protocol.
UUID, untagged, and discriminated to reduce duplication and minimize the need for complex transformations when moving between different Smithy-based tools (like smithy4s and smithy-translate).In the context of Smithy, a protocol is a set of concrete rules that define how data modeled in Smithy is transcribed into lower-level semantics (like HTTP).
Smithy is designed to be protocol-agnostic. This means the core language defines the structure of your API, while protocols provide the specific implementation details. To bridge the two, protocols rely on trait annotations. For example, the alloy#simpleRestJson protocol uses the smithy.api#http trait to determine which HTTP endpoint maps to a specific Smithy operation shape. Without these traits, the protocol-specific semantics cannot be applied to the model.
IOLocal (from cats-effect) is a construct that allows for sharing context across the scope of a Fiber.
IOLocal is accessible across the current Fiber.Fiber is forked, the value is carried over to the new Fiber.Fiber cannot update the value held by its parent or sibling fibers.This makes it ideal for request-scoped context in web servers, where each request is handled within its own fiber hierarchy.
Smithy4s translates Smithy traits (annotations) into smithy4s.Hints. A Hints instance is a polymorphic map keyed by ShapeTag (a uniquely identified tag using referential equality).
Every Schema can hold a Hints instance, allowing you to query trait values during serialization or deserialization. For example, the smithy.api#jsonName trait is translated to a smithy.api.JsonName Scala type that can be queried from the Hints instance to customize JSON field names.
Smithy4s is designed to derive client stubs and server routers by interpreting generated code. It uses polymorphic interpreters that operate on generated interfaces and schemas to transform high-level method calls into low-level requests (and vice versa).
To turn a method call into a network request, the flow is:
kvstore.get("key")KVStoreOp.Get("key")).Schemas (input/output) for that operation.GetInput => Request).Request => Response).Response => Output).To turn a network request into a method call, the flow is:
Request to an operation (e.g., via HTTP path).Schemas for the matched operation.Request => GetInput) and run it.KVStoreOp.Get).KVStore#get).GetOutput => Response).Smithy4s prioritizes model accuracy and idiomatic Scala experience over binary compatibility. As a result, evolving a Smithy schema may break binary compatibility in the generated Scala code.
Best Practices:
By default, Smithy does not distinguish between a missing field and a field explicitly set to null. To enable this distinction (e.g., for implementing merge patch semantics), use the @alloy#nullable trait on structure members.
In the generated Scala code, this results in a type of Option[Nullable[A]]:
None: The field is absent.Some(Nullable.Null): The field is explicitly set to null.Some(Nullable.Value(a)): The field has a specific value a.To convert between Option and Nullable, use Nullable.fromOption(option) and nullable.toOption.
namespace example
use alloy#nullable
structure Foo {
@nullable
a: Integer
}// Resulting Scala type: // final case class Foo(a: Option[Nullable[Int]] = None)
// Usage: // Foo(None) => Absence of value // Foo(Some(Nullable.Null)) => Explicit null // Foo(Some(Nullable.Value(1))) => Explicit value
When a Smithy service is annotated with the @simpleRestJson protocol, Smithy4s automatically generates an OpenAPI "view" for that service at build-time. This allows you to serve interactive documentation via Swagger UI.
Example Smithy definition:
namespace smithy4s.example
use alloy#simpleRestJson
@simpleRestJson
service HelloWorldService {
version: "1.0.0"
operations: [Hello]
}Smithy uses traits (annotations) to associate protocol-specific details, such as HTTP semantics, with data models and services. You can apply traits like @http to operations, @httpLabel to structure members to match URI path parameters, and @httpPayload to indicate the body of a request or response. Error shapes can be annotated with @error and @httpError to define client/server error types and status codes.
namespace foo
@http(method: "GET", uri: "/hello/{name}")
operation Greet {
input: GreetInput,
output: GreetOutput,
errors: [BadInput]
}
structure GreetInput {
@httpLabel
name: String
}
structure GreetOutput {
@httpPayload
message: String
}
@error("client")
@httpError(400)
structure BadInput {
@jsonName("oops")
message: String
}