disneystreaming / alloy

Alloy

A collection of commonly used Smithy shapes.

Table of Contents

• Why Alloy?
• Core alloy library
  • Constraints and behavioural traits
  • Serialisation
  • Protocols
• Protocol Compliance Module
• Working on Alloy
  • Publish Local
  • Run Tests

Why Alloy?

Alloy is smithy library that contains traits and protocols that are not currently provided by the smithy standard library. Alloy can be seen as a companion library to the smithy standard library (smithy.api).

The goals of alloy are :

• provide traits aiming at expressing protobuf/gRPC semantics in smithy
• provide traits allowing to capture patterns and constraints that are common in the industry (some related to http APIs, some more general)

Core alloy library

The core alloy library, containing shapes and validators, is published to Maven Central at the following coordinates.

com.disneystreaming.alloy:alloy-core:x.y.z

It contains, in particular, traits and validators associated to the following aspects :

Constraints and behavioural traits

Alloy provides a number of constraint and behavioural traits that may be leverage by tooling and protocols.

Serialisation

Alloy defines a number of behavioural traits that can be leveraged by protocols to tweak serialisation. In particular for the following formats :

• JSON
• Protobuf
• URL Form Data

Protocols

Alloy defines two protocols :

• alloy#simpleRestJson
• alloy#grpc

Protocol Compliance Module

Alloy provides a suite of protocol tests that utilise the [AWS HTTP Protocol Compliance Test Module]("https://smithy.io/2.0/additional-specs/http-protocol-compliance-tests.html. These tests accompany the specification of the alloy#simpleRestJson protocol, allowing implementations of that protocol to build confidence that the implemented behaviour is correct as per the specification.

These tests are available on maven central at the following coordinates :

com.disneystreaming.alloy:alloy-protocol-tests:x.y.z

Working on Alloy

Publish Local

> ./mill __.publishLocal

Run Tests

> ./mill __.test

alloy's Issues

`JsonName` ignored in examples when generating swagger docs

If a structure member has a custom @JsonName:

$version: "2.0"
namespace example.hello
operation Hello {
    output: Greeting
}
structure Greeting {
    @required
    @jsonName("msg")
    message: String
}
apply Hello @examples([
    {
        title: "My name is Jeff"
        output: {
            message: "Hello Jeff"
        }
    }
])

the generated swagger doc for the above service would ignore the @JsonName and use message instead of msg:

I think this is wrong. Smithy docs mention useJsonName which might be of relevance but I couldn't find a way of setting that in the interface provided by smithy4s.http4s.swagger.docs.

Also note that in my example, I had to provide the output example as a smithy structure rather than a json. ie {message: "Hello Jeff"} rather than msg, which I'd argue, is a little counter intuitive for the reader. I understand this is perhaps one for smithy but do we know if it Would be possible to specify examples in json rather than smithy structures? 🤔

Alloy OpenApi module import issue

When adding "com.disneystreaming.alloy:alloy-openapi:x.x.x" as
val alloyOpenApi = "com.disneystreaming.alloy" % "alloy-openapi" % AppVersions.alloy
sbt fails to retrieve the module. After I took a look at maven central it seems it is only published with the _2.12 and _2.13 suffixes.

Add protocol compliance tests for nullable

A couple protocol compliance test should be specified to express the expected behaviour of nullable members

https://github.com/disneystreaming/alloy/tree/main/modules/protocol-tests/resources/META-INF/smithy

Fields annotated with uuidFormat should result in uuid formatted string in the generated swagger docs

If I make a field like:

@alloy#uuidFormat
string UserId

The generated swagger type unfortunately does not end up as a uuid formatted string in swagger.

uuid is mentioned here as a possible string format.

allow specifying open api servers when constructing swagger docs

👋🏽

open api allows specifying "servers" in a spec so that the user can toggle between them when trying to hit the apis. They allow both absolute and relative urls.

My own use case is the relative url. more specifically, this: smithy-lang/smithy#2233

Be nice to add them. Guessing it's not a priorirty in which case, please point out where in the code this could/should be done.

Link to constraints and behavioural traits in Readme is broken

In this section:
https://github.com/disneystreaming/alloy?tab=readme-ov-file#constraints-and-behavioural-traits

There is a link to:
https://github.com/disneystreaming/alloy/blob/main/docs/misc/behaviour.md

But it seems like maybe it was split into separate files since I do see a constraints and a documentation md file in the same folder. I wasn't sure what the intent should be now so I didn't open up a PR to fix it.

Add protocol compliance tests for union encodings

Some protocol compliance tests should be specified for the various encodings of unions that are specified in alloy :

https://github.com/disneystreaming/alloy/tree/main/modules/protocol-tests/resources/META-INF/smithy

Support @nullable in simpleRestJson smithy to openapi conversion

This should be done by adding a new JsonSchemaMapper such as this one to annotate an openapi schema corresponding to a smithy-shape with nullable: true

See https://swagger.io/docs/specification/data-models/data-types/ (ctrl-f "nullable")