Skip to content

v0.18.0 : towards multi-protocol
Compare
Choose a tag to compare
@kubukoz kubukoz released this 23 Aug 00:04
· 509 commits to series/0.18 since this release
v0.18.0
518675f
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

0.18.0

This 0.18.0 release of Smithy4s contains a significant rewrite of the abstractions and the internals that compose the library. It is motivated by a desire to facilitate the catering to two orthogonal use-cases :

  • implementation of different protocols.
  • integration with other http libraries than the one we provide out-of-the-box.

This release is neither source nor binary compatible with the previous ones, and also forces some users to update their Smithy specifications. Please read the next section carefully.

This release also comes with a number of user-facing improvements.

Behavioural changes

The default timestamp format in Json serialisation is now EPOCH_SECONDS. This change is motivated by a desire to align with AWS and to improve our compatibility with their tooling. Timestamps shapes (or members pointing to timestamp shapes) now will need to be annotated with @timestampFormat("DATE_TIME") in order to retrieve the previous behaviour.

Significant rewrite of the abstractions.

The abstractions that power smithy4s have been overhauled to facilitate integration with other protocols than simpleRestJson and other http libraries than http4s. Many levels of the library has been impacted in significant ways, which is likely to break a great many third-party integrations. The amount of breaking changes is too large to list exhaustively, therefore only a highlight is provided in this changelog.

  • smithy4s.schema.Field is no longer a GADT differentiating from required/optional fields. There is now a smithy4s.schema.Schema.OptionSchema GADT member instead, which was required to support some traits.
  • smithy4s.schema.Schema.UnionSchema now references an ordinal function, as opposed to the previous dispatch function.
  • smithy4s.Endpoint now contains a smithy4s.schema.OperationSchema, which is a construct gathering all schemas related to an operation.
  • smithy4s.Endpoint.Middleware now generalises the concept of "endpoint-specific middleware" to non-http4s centric usecases. It does however loses the Monoid instance, as it now lives in the interopcats package provided by the smithy4s-cats module.
  • smithy4s.Service now allows to get an ordinal value out of a reified operation, thus making it easier to dispatch it to the correct handler.
  • smithy4s.Service now contains some methods for instantiation of services from an endpoint compilers.
  • Two new packages in core have appeared : smithy4s.server and smithy4s.client, each containing protocol-agnostic constructs that aim at taking care of some of the complexity of integrating libraries/protocols with smithy4s.
  • A smithy4s.capability.MonadThrowLike and smith4s.capability.Zipper types have been created, unlocking the writing of generic functions that benefits integrations
    with various third-party libraries.
  • smithy4s.http.HttpRequest and smithy4s.http.HttpResponse types have been created.
  • smithy4s.http.HttpUnaryClientCodecs and smithy4s.http.HttpUnaryServerCodecs are new constructs that aim at facilitating the integration of http-protocols. In particular, they take care of a fair amount of complexity related to handling smithy.api#http* traits (including the reconciliation of data coming from http metadata and http bodies).
  • Overall, the amount of code in the smithy4s-http4s module has drastically diminished, as the constructs necessary for the generalisation of the http-related logic have been created. We (maintainers) love http4s, and are not planning on publicly maintaining any other integration, but we are responsible for other integrations in our work ecosystem. Therefore, generalising what we can makes our jobs easier, but also should allow for third parties to have an easier time integrating their http-libraries of choice with Smithy4s.

Highlight : schema partitioning

The most ground-breaking change of 0.18, which is crucial for how things are now implemented, is the addition of a smithy4s.schema.SchemaPartition utility that allow to split schemas into sub-schemas that each take care of the subset of the data. This mechanism allows to completely decouple the (de)serialisation of http bodies from the decoding of http metadata. This means, for instance, that JSON serialisation no longer has to be aware of traits such as httpHeader, httpQuery, httpLabel. This greatly facilitates the integration of other serialisation technologies (XML, URL Form, etc) as these no longer have to contain convoluted logic related to which fields should be skipped during (de)-serialisation.

As a result, the smithy4s-json module has been rewritten. In particular, the code it contains is now held in the smithy4s.json package, since it is no longer coupled with http-semantics. The smithy4s.json.Json object has also been created to provide high-level methods facilitating the encoding/decoding of generated types into json, which is helpful for a number of use-cases that fall out of the server/client bindings.

Features

AWS SDK support.

Smithy4s' coverage of the AWS protocols has increased drastically. Now, the vast majority of services and operations are supported. This does mean that Smithy4s can effectively be used as a cross-platform AWS SDK (with caveats), delegating to http4s for transport.

The Smithy4s build plugins now also come with utilities to facilitate the code-generation from AWS service specifications.

Please refer yourself to the relevant documentation page.

Build plugins

Smithy has support in IDE via the smithy-language-server. The language server uses a configuration file to understand your project. In 0.18, our build plugins for sbt and mill can generate that configuration file for you. Use the following commands depending on the build tool you use, for sbt: sbt smithy4sUpdateLSPConfig and for mill: mill smithy4s.codegen.LSP/updateConfig.

Mill

The mill plugin is build for version 0.11.0. The changes to the API are solely results of this migration.

The most important migration bits:

  1. Change from def smithy4sInputDirs: mill.define.Sources to def smithy4sInputDirs: mill.define.Target[Seq[PathRef]]
  2. Change from def manifest: T[mill.modules.Jvm.JarManifest] to def manifest: T[mill.api.JarManifest]
  3. Change from def smithy4sAllExternalDependencies: T[Agg[Dep]] to def smithy4sAllExternalDependencies: T[Agg[BoundDep]]

Cats Module

Addition of a cats module to contain SchemaVisitor implementations of commonly-used cats typeclasses. Currently included are cats.Show and cats.Hash (note that cats.Eq is provided by the cats.Hash implementation).

See #921

Structure Patterns

Allows for marking string types with the alloy#structurePattern trait. This trait indicates that a given pattern, with parameters, applies to a given string and that this string should
actually be parsed into a structure where the members of the structure are derived from the parameters in the string pattern.

See #942

Non-Orphan Typeclass Instances

Allows creating implicit typeclass instances in the companion objects in the smithy4s-generated code. This is useful for creating instances of
typeclasses such as cats.Show, cats.Eq or any others you may be using.

See #912

smithy4s.Blob

smithy4s.ByteArray has been deprecated in favor of smithy4s.Blob. This new type is more flexible, in that it can be backed by byte arrays and byte buffers alike.
Additionally, it allows for O(1) concatenation. This change is motivated by a desire to ease integration with third party libraries whilst reducing the need of copies of binary data.

Smithy4s Optics Instances

When the smithy4sRenderOptics setting is enabled, Lenses and Prisms will be rendered in the companion objects of the generated code when appropriate.

See #1103

Open Enumerations

Introduces alternative code generation for enums and intEnums when they are marked with the alloy#openEnum trait.

See #1137

Union Projections and Visitors

Added convenient methods for working with unions including projectors for each union alternative and a visitor in union companion objects that can be passed to each union's new accept method.

See #1144

Sparse collections

The sparse trait is now supported, allowing for the modelling of collections with null values. Its presence leads to the code-generation of List[Option[A]] and Map[String, Option[A]].

See #993

Xml support

The smithy4s-xml now exists, containing utilities to parse XML blobs into the generated data classes, and render XML from the generated data classes. This serde logic abides by the rules described in the the official smithy documentation.

application/x-www-form-urlencoded support

The smithy4s-core now contains utilities to parse application/x-www-form-urlencoded payloads into the generated data classes, and render those payloads same payloads the generated data classes. This encoding allows for a few customisation, driven by alloy traits.

See #1113

What's Changed

New Contributors

Full Changelog: v0.17.19...v0.18.0

Contributors

jgoday, miguel-vila, and 15 other contributors
Assets 2
Loading