Releases: disneystreaming/smithy4s
v0.18.0 : towards multi-protocol
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 asmithy4s.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 asmithy4s.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 theMonoid
instance, as it now lives in theinteropcats
package provided by thesmithy4s-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
andsmithy4s.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
andsmith4s.capability.Zipper
types have been created, unlocking the writing of generic functions that benefits integrations
with various third-party libraries. smithy4s.http.HttpRequest
andsmithy4s.http.HttpResponse
types have been created.smithy4s.http.HttpUnaryClientCodecs
andsmithy4s.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 handlingsmithy.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:
- Change from
def smithy4sInputDirs: mill.define.Sources
todef smithy4sInputDirs: mill.define.Target[Seq[PathRef]]
- Change from
def manifest: T[mill.modules.Jvm.JarManifest]
todef manifest: T[mill.api.JarManifest]
- Change from
def smithy4sAllExternalDependencies: T[Agg[Dep]]
todef 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
v0.17.18 - bugfix release
What's Changed
Full Changelog: v0.17.17...v0.17.18
v0.17.17: Updates to simpleRestJson http tests
What's Changed
Full Changelog: v0.17.16...v0.17.17
v0.17.16: HEAD Response Fix
Fixes a bug where HEAD responses contained an empty {}
in the body (where there should be no body present).
What's Changed
Full Changelog: v0.17.15...v0.17.16
v0.17.15: Fixes for intEnum trait rendering
Updates to fix compile errors when intEnum shapes are used as traits.
What's Changed
Full Changelog: v0.17.14...v0.17.15
v0.17.14
v0.17.13
What's Changed
Backport service interpreter by @miguel-vila in #1118
Adds useful utilities for working with service interpreters, which should make it much easier to create interpreters that work efficiently.
Fix rendering of deprecated annotation in mixins by @ghostbuster91 in #1123
Resolves a bug that would previously result in codegen producing code that fails to parse and compile.
Internal changes
New Contributors
- @ghostbuster91 made their first contribution in #1123
Full Changelog: v0.17.12...v0.17.13
v0.17.12
What's Changed
Remove a legacy mechanism of dealing with name conflicts in generated types. Fixes #1051
- Flatten AWS newtypes by @denisrosca in #1110
Adjusts the rendering of Smithy shapes from AWS specs, as it would've often been inconvenient due to the change above.
- Bump webjar dependency to 0.47 by @daddykotex in #1100
Updates a previously frozen dependency to alleviate potential security issues.
New Contributors
- @denisrosca made their first contribution in #1110
Full Changelog: v0.17.11...v0.7.12
v0.17.11 - AWS bugfix, client methoddeprecation, internal refactors
This is mostly a bugfix and cleanup release.
What's Changed
Resolves a case-sensitivity issue in the file-based AWS credentials provider.
Deprecates a method - the migration path would be just to move to another one with the same shape.
- Error transformations as middleware by @msosnicki in #1084
Changes the error transformation logic in the http4s servers so that it's implemented using the (public) per-endpoint middleware construct.
Full Changelog: v0.17.10...v0.17.11
v0.17.10 - bugfix release
What's changed
- Revert original behavior where middleware get all errors by @daddykotex in #1034
This change adds a fix for an accidental behavior change around error handling/capture in middlewares.
Other changes
- Adding a comment in flatMapErrors by @msosnicki in #1030
Full Changelog: v0.17.9...v0.17.10