This file serves as a template for release notes in GitHub releases. When adding entries, please treat them as if they could end up in a release any time. This makes it much easier for us to make frequent releases!
Thank you!
- Add
getMessageimplementation inSmithy4sThrowablewhich will be overridden in cases where the error structure contains a message field, but otherwise will be used to prevent a uselessnullresult whengetMessageis called.
Validated newtypes #1454
Add support for rendering constrained newtypes over Smithy primitives as validated newtypes. These types now have an apply method which returns either an error or a validated value.
- Add support for
@defaultforTimestampfields in disneystreaming#1557
- Addition of a new
@scalaImporttrait to provide a mechanism to add additional imports to the generated code. Read the new docs for more info (see disneystreaming#1550). - Added support for parsing timestamps without seconds in disneystreaming#1553.
- Change semantics of
Blob.equals- Blobs do not take underlying type into consideration, just bytes in disneystreaming#1526
WARNING: This release includes binary-breaking changes in the core module. This is indirectly caused by an upstream change in smithy-lang/smithy.
In the vast majority of applications using Smithy4s, it will not cause runtime issues. However, in the unlikely event that you have custom interpreters that query the .breakingChanges field of a Trait hint, or have that field populated by a non-stdlib trait/hint, you'll have to ensure that all the libraries pulled by your application are compiled against smithy4s 0.18.19 or above.
In sbt, you can check what versions of smithy4s are used by your dependencies using the whatDependsOn task.
We apologize for the inconvenience.
smithy4sUpdateLSPConfig: Replaceimportswithsourcesto be more in line with idiomatic smithy-build config in disneystreaming#1518 (see disneystreaming#1459)- Update smithy: 1.45.0 to 1.49.0 (binary breaking) in disneystreaming#1485
- Rendered type aliases are now sorted alphabetically in disneystreaming#1523
- Add handlers construct to facilitate the decoupling of operation implementations in disneystreaming#1522
- Improve cache in code generation (sbt) in disneystreaming#1499
- Fix an issue in the ADT trait validators that would sometimes fail validation while they shouldn't. disneystreaming#1514
- Constraints applied to list or map members are now correctly rendered in the generated code.
- Makes the json decoding of tagged-unions lenient for AWS
- Fix an issue with duplicated entries in generated smithy-build.json file (#1491)
- Add support for passing custom OpenAPI config via a
smithy-build.jsonfile - Fix a bug when using
adtwith mixins, see #1457
- Fixes bug leading to refined case-class fields being rendered with default values of the wrong type
- Adds a
smithy4s-protobufmodule, containing derivation logic for protobuf codecs. See disneystreaming#1455 - Add support for converting smithy4s services and schemas to smithy models
- Add
smithy4s.meta#onlyannotation allowing to filter operations in services, intended to reduce the amount of code generated from AWS specs
- Add support for injecting endpoint-specific middlewares in AWS clients
- Fixes a bug in the parsing of AWS credentials files
- Add support for decoding Document representations of untagged unions
- Update aws-http4s clients using json to have a maxArity of Int.MaxValue
- Enable generation of protobuf specifications from smithy specifications.
- modify logic to guarantee that rendered and dynamic enum values respect the ordering from the specification.
- fix issue where schemas for fields of generated big structs (over 22 fields in size) would not be ordered correctly
- smithy4s Structure schemas are now retaining the original order of fields, as per the specification.
- Added a utility method,
Schema.transformTransitivelyK, to help in recursively transforming schemas. In addition, the semantics oftransformHintsTransitivelyhave been changed: the transformation no longer modifies the hints on the result of thetotalfunction. - smithy4s-core now contains the generated code for the alloy.proto namespace
- Bumps alloy to 0.3.1. This is required as otherwise the
alloy#nullablehints get filtered out when using SimpleRestJsonBuilder.
-
Fix bug that would lead to special characters being escaped in XML attributes, which are already quoted
-
Generalise implementation of
@httpResponseCodeto later allow for its use in error responses. -
Fix in Bijection#identity which caused and infinite recursion, fixed in 1401
-
Adds a
Field#addHints(hints: Hints)method -
Adds a
Hints.dynamic(bindings: (String, Document)*)hints creation method -
Adds a
smithy4s.Document.syntaxobject, the contents of which can be imported to facilitate the instantiation of documents. -
Added support for
@nullableon fields, to allow absent values to be handled differently from explicit null
- Fix collision avoidance algorithm to cover Scala 3 keywords
- Added support for
@httpResponseCodeon newtypes (integer shapes that aren't exactlysmithy.api#Integer), as well as refinements (e.g. ints with a@rangeconstraint).
-
If a Smithy trait, being a structure shape, had a Scala keyword in its member names, compilation of the generated would fail. In addition, enumeration values that matched a known keyword would have their name erroneously escaped with an underscore in the string literal. These are now fixed in #1344.
-
Smithy4s specific logic to extract manifest from jars should not run on jar. Fixed in #1351.
-
In some concurrent scenarios, especially those of concurrent initialization of objects (e.g. tests), your application would previously be at risk of deadlocking due to #537. This is now fixed by suspending evaluation of hints in companion objects using the
.lazilyconstruct: see #1326. -
Allow to configure how the default values (and nulls for optional fields) are rendered. Fixed in #1315
- When encoding to
application/x-www-form-urlencoded, omit optional fields set to the field's default value.
-
Changes the behaviour of
Field#getUnlessDefaultandField#foreachUnlessDefaultto always take the value into consideration when thesmithy.api#requiredtrait is present on the field. This leads to field values being always serialised even when their values match their defaults, as this abides by least-surprise-principle. -
Fix sbt
smithy4sUpdateLSPConfigand millsmithy4s.codegen.LSP/updateConfigrendering of repositories.
- Support constraint traits on members targeting enums
Although it's weird to allow it, it is actually supported in Smithy.
- Tweak operation schema
*Inputand*Outputfunctions
Some schema visitor will adjust their behaviour if a shape is the input or the output of an operation. For this reason we have a InputOutput class with a Input and Output hint that you can add to schemas to adjust the behaviour. OperationSchema has functions to work on input schemas and output schemas of an operation. This change makes these functions automatically add the relevant hint.
- OptionDefaultVisitor supports bijection
When the schema for the member of a structure is a bijection, and the structure is meant to be decoded from metadata (like http headers), optionality was disregarded. This was making optional member required when decoding.
- Fixing AwsInstanceMetadata codec in #1266
Resolves an issue in which AWS credentials would be decoded using the wrong timestamp format, affecting AWS clients on EC2/ECS.
- Render explicit type annotations for some methods that were missing them in #1272
This resolves a problem in which type inference would have different results between Scala 2.13 and 3.x, causing an error on Scala 2.13 under the -Xsource:3 flag.
- Override
toStringon error shapes
Default toString implementation on Throwable prints the class name, instead, we decided to rely on a custom toString implementation.
In 0.18.0, support was added for application/x-www-form-urlencoded data. But, many of its related constructs were private, they are now public for users to access them directly.
disneystreaming#1254
In 0.18.0, support was added for open enums in smithy4s-generated code. This release extends that support to runtime (dynamic) schemas.
This model-preprocessor aims at removing constraints from output types in AWS specs (as AWS doesn't seem to respect said constraints) disneystreaming#1251
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.
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.Fieldis no longer a GADT differentiating from required/optional fields. There is now asmithy4s.schema.Schema.OptionSchemaGADT member instead, which was required to support some traits.smithy4s.schema.Schema.UnionSchemanow references an ordinal function, as opposed to the previous dispatch function.smithy4s.Endpointnow contains asmithy4s.schema.OperationSchema, which is a construct gathering all schemas related to an operation.smithy4s.Servicenow allows to get an ordinal value out of a reified operation, thus making it easier to dispatch it to the correct handler.smithy4s.Servicenow contains some methods for instantiation of services from an endpoint compilers.- Two new packages in
corehave appeared :smithy4s.serverandsmithy4s.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.MonadThrowLikeandsmith4s.capability.Zippertypes have been created, unlocking the writing of generic functions that benefits integrations with various third-party libraries. smithy4s.http.HttpRequestandsmithy4s.http.HttpResponsetypes have been created.smithy4s.http.HttpUnaryClientCodecsandsmithy4s.http.HttpUnaryServerCodecsare 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-http4smodule 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.
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 has 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 usecases that fall out of the server/client bindings.
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.
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.
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.Sourcestodef 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]]
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).
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.
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.
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.
When the smithy4sRenderOptics setting is enabled, Lenses and Prisms will be rendered in the companion objects of the generated code when appropriate.
Introduces alternative code generation for enums and intEnums when they are marked with the alloy#openEnum trait.
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.
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]].
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.
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.
- Add empty line separating generated case classes from their companion objects in #1175
This release brings in a smithy-model update, which resolves some issues that would've prevented code generation from succeeding. #1164
Fixes a ClassCastException in document encoding in #1161
More permissive test for HEAD requests in #1157
Fixes a bug where HEAD responses contained an empty {} in the body (where there should be no body present). #1149
Updates to fix compile errors when intEnum shapes are used as traits. #1139
- Only transform AWS shapes named after standard shapes in #1127
- Fixes AWS AwsStandardTypesTransformer bug by in 1129
- Backports Service interpreter logic introduced in #908.
- Fixes rendering of deprecated annotations in mixins in #1123
- Remove reserved types in disneystreaming#1052
Remove a legacy mechanism of dealing with name conflicts in generated types. Fixes #1051
- Flatten AWS newtypes in disneystreaming#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 in disneystreaming#1100
Updates a previously frozen dependency to alleviate potential security issues.
This is mostly a bugfix and cleanup release.
- [aws] Keep casing in file credential provider in disneystreaming#1076
Resolves a case-sensitivity issue in the file-based AWS credentials provider.
- Deprecate
ClientBuilder.use, add.makein disneystreaming#1073
Deprecates a method - the migration path would be just to move to another one with the same shape.
- Error transformations as middleware in disneystreaming#1084
Changes the error transformation logic in the http4s servers so that it's implemented using the (public) per-endpoint middleware construct.
- Revert original behavior where middleware get all errors in disneystreaming#1034
This change adds a fix for an accidental behavior change around error handling/capture in middlewares.
- Adding a comment in flatMapErrors in disneystreaming#1030
- Update smithy-model to 1.31.0, alloy to 0.2.2 in disneystreaming#1022
- backport of [improve: fallback unspecified members of deprecated trait to N/A] in disneystreaming#989
- Dynamic module guide in disneystreaming#960
- Add an option to encode missing fields as nulls in disneystreaming#995
Make sure error handling logic in routing is applied before and after middleware application .
- Add course link to learning resources in disneystreaming#965
- Http4s: pre- and post-error handling middleware in disneystreaming#877
This release is backward binary-compatible with the previous releases from the 0.17.x lineage.
- Fixes a bug related to swagger-ui redirects that would occur with empty paths.
- Fixes a bug related to the undocumented "dynamic" module not respecting the order of fields specified in smithy models
This release is backward binary-compatible with the previous releases from the 0.17.x lineage. However, the generated code produced by this version is not entirely source-compatible with the previous version. More info below.
This version introduces changes in how the code is rendered that may result in some breakage in userland. We've carefully architected the changes to reduce the likelihood of breakage happening.
A number of constructs are now rendered not in the companion object of the generated service, but rather in the companion object of the reified operation type. These constructs include the error types that get generated by operations.
This change has been performed in order to eliminate the risk of collision between the generated types and some type
members present in the smithy4s.Service interface. This collision, when it happened, was making the code impossible to
compile.
In order to reduce breakage around the error types (which are likely to be used in userland), we have decided to generate aliases at the location where they used to live. The generated code should not break source compatibility in the large majority of usage of Smithy4s.
A small minority of users may have to change how they access the generated constructs they may have depended on. This is unlikely, as the constructs in question are used internally by interpreters via interfaces that haven't changed, and they are not constructs that are advertised in our documentation. We only expect some possible breakage in advanced usage performed by a handful of people.
See:
Changed the handling of the httpQueryParams (plural) trait so that possible httpQuery-annotated fields do not take priority
over it during decoding. This means that httpQueryParams receive the whole set of query parameters, which may induce duplication
with the value contained by overlapping httpQuery-annotated fields.
On the encoding side, the behaviour is that httpQuery fields have priority over httpQueryParams fields.
This is a more faithful implementation of the spec.
Adds logic to validate the model after pre-processing model transformations (before the code-generation)
AWS has changed the Smithy specification of the DATE_TIME timestamp format to precise that numeric offsets should be handled.
This is now the case.
The currently undocumented dynamic module has received an improvement allowing to access the metadata
of the loaded models via its platform-agnostic interface.
Empty bodies are now correctly using the built-in withEmptyBody of Http4s, which correctly removes
the Content-Type header from the request upon usage. This solves issues when Smithy4s is being called
(or calling) strict clients/servers that check this type of thing.
The AWS Json protocols specify that NaN, Infinity and -Infinity are valid values for Double and Float types.
This is now handled.
A bug was preventing dependencies that would have special characters in their absolute paths to be loaded successfully. This is now fixed.
Byte fields are now correctly supported when used by an httpLabel member.
This release is backward binary-compatible with the previous releases from the 0.17.x lineage.
This release is backward binary-compatible with the previous releases from the 0.17.x lineage.
Under certain conditions, it is now possible to annotate union shapes with @adt, which has the effect of inlining
all the structure shapes under it directly in the companion object of the union, as opposed to create Case-suffixed
wrappers. Additionally, when a union is annotated with @adt, the intersection of mixin shapes that are applied to every member of the union is now used as Scala-level mixin traits. This facilitates object-oriented usage of Smithy4s.
Read the new docs for more info.
Smithy @documentation traits (which has syntactic sugar in the form of triple-slashes-prefixed comments) is now used to generate Scaladoc above the relevant data-types, interfaces and methods that get generated in Smithy4s.
Thank you @zetashift for this awesome contribution and @msosnicki for this valuable contribution !
Under conditions which should automatically be propagated from the build-tool to the code-generation, Scala 3 wildcards now get generated instead of Scala 2 wildcards. This makes user experience better on Scala 3, as syntax deprecation warnings will no longer be issued.
Thank you @albertpchen for this awesome contribution !
It is now possible to directly instantiate AWS clients against a Monadic context, which makes for a better UX when calling unary request/response operations. When using that mode, stream operations being called such clients will fail with a raised exception.
It is now possible to load credentials from an AWS-compliant configuration file (typically found under ~/.aws/credentials). This is wired by default in the clients, and has lower precedence than the other providers.
We've improved and added new sections to the documentation, in particular around AWS SDK usage and model pre-processing.
The default trait allows for not setting a value. Now, the absence of value (ie null) in the default trait at the smithy level translates to the correct "zero" value of the target type.
Null documents were not being decoded as None, but rather were leading to decoding failures
when decoding data types from smithy4s.Document
The URI was previously using the wrong relative path
Loading a smithy 1.0 model with smithy 2.0 tooling (which Smithy4s uses) leads to the automatic addition of "default" traits on some shapes and members. When combined with refinements, this had the side effect of treating the refined type as required when it should be in fact optional. It's all the more confusing that there is no mechanism in place to reconcile refinement logic, with default values, as refinement logic is expressed in run-time code whereas default value validation is expressed in build-time code.
Yet another awesome contribution from @plokhotnyuk to shave allocations off the Json parsing logic, leading to performance improvements.
Our implementation of our alloy#simpleRestJson protocol is now derived automatically from test specifications
written in Smithy itself
See:
This also paves the road for testing our implementation of the AWS protocols using official tests, which are located [there]
Some tweaks were made to the smithy4s.Enumeration.Value interface to allow for more generic logic using enumerations.
This release is backward binary-compatible with the previous releases from the 0.17.x lineage.
In order to render Operation errors as Scala 3 union types, a following metadata flag needs to be added: metadata smithy4sErrorsAsScala3Unions = true (in any of the smithy files that are used for code generation).
This will make it easier to run front-end debuggers on webpage build with smithy4s-issued clients
it's now possible to invoke transformations more conveniently in polymorhic code, via a method in the Transformation companion object
It is now possible to define static query parameters when using the http trait :
@http(method: "GET", uri: "/foo?bar=baz)
operation Foo {}Service interfaces now receive the set of all operations tied to resources transitively tied to the service
For instance, when running the code-generator, the Library interface will now receive a getBook method, which
wasn't previously the case
service Library {
resources: [Book]
}
resource Book {
read: GetBook
}
@readonly
operation GetBook {
}- Various codegen fixes and improvements by @Baccata in disneystreaming#677
- fix for timestamp format issue for aws tests by @yisraelU in disneystreaming#675
- Make whitespace around colons consistent by @kubukoz in disneystreaming#682
- Add resource operations to generated service by @Baccata in disneystreaming#686
- fix path segment parsing when suffixed with query by @yisraelU in disneystreaming#689
- Compliancetests fixes improvements by @yisraelU in disneystreaming#680
- restructured timeout call and attemptNarrow by @yisraelU in disneystreaming#708
- [compliance tests] addresses timeouts on the server side by @yisraelU in disneystreaming#712
- Fix ShapeId.parse not working for valid shapes by @kubukoz in disneystreaming#714
- codegen cli should use a non-zero exit code when failing by @daddykotex in disneystreaming#713
This 0.17.0 release of Smithy4s brings a number of improvements on the abstractions implemented by the generated code, in particular in terms of flexibility and user experience.
This release also aims at bringing inter-operability with other tools and projects that Disney Streaming is putting forward to reinforce the Smithy ecosystem, such as smithy-translate and alloy.
In order to achieve these improvements, we've had to break a number of things at different levels. This release is therefore neither source nor binary compatible with the previous ones, and also forces the user to update their Smithy specifications.
The Smithy shapes that were previously residing under smithy4s.api namespace have moved to the alloy namespace. Alloy is a standalone library containing Smithy shapes and validators, defined here.
The reason for us to bring this change is to have a language specific location to define shapes that are relevant to the protocols/runtime-behaviours we're putting forward, that could be used by tooling working with other languages than Scala. It was important for us to lose the 4s suffix, which is short for for Scala.
This change implies, for instance, that any use of smithy4s.api#simpleRestJson in your specification will have to be replaced by alloy#simpleRestJson.
Note that this change, in use cases that follow our documentation, should have no visible effect in the Scala code.
The smithy4sInputDir setting/task in SBT/mill has been replaced by smithy4sInputDirs, allowing the user to set several directories where the plugins should look for Smithy files.
We've changed the smithy-sharing mechanism to do two things:
- By default, any dependency declared "normally" in SBT or mill, by means or
libraryDepedencies ++=ordef ivyDeps, will be inspected for Smithy files after being resolved. This means that, for instance, if your application has a runtime dependency on a library that was built with Smithy4s and contains Smithy files, your local specs can use the code defined in these Smithy files to create or annotate new shapes. You no longer need to declare those using% Smithy4sordef smithy4sIvyDeps: these are now reserved for libraries containing Smithy files that you do not want your application's runtime to depend on. - Libraries built by Smithy4s automatically track the dependencies that they used during their own code-generation, by storing some metadata in their Jar's manifests. By default, the Smithy4s plugins will also pull those dependencies (which will have been declared upstream using
% Smithy4sin SBT ordef smithy4sIvyDepsin mill), for your project's code generation. This facilitates the transitivity of specification-holding artifacts. This mechanism is used, for instance, to communicate to users projects the fact that Smithy4s depends on shapes that are defined in the alloy library, and that these shapes should be made available to user projects, without impacting the user's application runtime, and without requiring any setup from the user.
Depending on your setup, it may be a breaking change, but @deprecated Smithy-traits now translate to the @deprectated Scala annotation in the generated code. For instance, if you used @enum heavily, you'll probably deprecation warnings in your console when compiling. Depending on your scalacOptions, it is possible that these warnings turn into errors. If you want to silence these particular errors while upgrading, you can do the following:
scalacOptions ++= Seq(
"-Wconf:msg=object Enum in package api is deprecated:silent",
"-Wconf:msg=type Enum in package api is deprecated:silent",
// for Scala 3
"-Wconf:msg=object Enum in package smithy.api is deprecated:silent",
"-Wconf:msg=type Enum in package smithy.api is deprecated:silent"
)If you use Smithy4s in the ways that were previously advertised in the documentation, you may have to perform some small adjustments.
In particular, the simpleRestJson extension method that was added to implementations of service-interfaces generated by Smithy4s is now removed, in favour of the SimpleRestJsonBuilder construct (which now works for any service Smithy shape that will have been annotated with alloy#simpleRestJson).
Additionally, some methods that were deprecated in 0.16.x releases have been removed.
The abstractions that the generated code implements and that the runtime interpreters use have undergone some massive changes.
Non-exhaustive list of symbol renames :
| old | new |
|---|---|
| smithy4s.Monadic | smithy4s.kinds.FunctorAlgebra |
| smithy4s.Interpreter | smithy4s.kinds.FunctorInterpreter |
| smithy4s.Service#asTransformation | toPolyFunction |
| smithy4s.Service#transform | fromPolyFunction |
| smithy4s.PolyFunction | smithy4s.kinds.PolyFunction |
| smithy4s.Transformation | smithy4s.kinds.PolyFunction5 |
| smithy4s.GenLift[F]#λ | smithy4s.kinds.Kind1[F]#toKind5 |
- Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the
project/Boilerplate.scalafile) to ensure the consistency of the various ways they are being used. This means thatsmithy4s.PolyFunctionhas moved tosmithy4s.kinds.PolyFunction, and that the previoussmithy4s.Transformationis nowsmithy4s.kinds.PolyFunction5. This decision ripples in thesmithy4s.Serviceinterface, which now sportstoPolyFunctionandfromPolyFunctionmethods, allowing to turn a finally-encoded implementation into a final one.smithy4s.kinds.PolyFunction2is also a thing, and may be used in bi-functor contexts. kind-specific types were created to facilitate the "lift" of constructs to the right kinds. For instance, when inspecting the internals of this library, you might see things likeKind1[IO]#toKind5where it was previouslyGenLift[IO]#λ. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will).smithy4s.Transformationis now a typeclass-like construct, which expresses the fact that a construct can be applied like a function. This construct is used by thetransformmethod that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces.- The
Serviceinterface takes a singleAlgtype parameter, theOpparameter has moved to type-member position, facilitating implicit search in some contexts (as well as the writing of some logic). - A bunch of path-dependent type aliases were created in the
Serviceinterface. - The
compliancetestmodule has changed drastically in UX. For those not aware, this module allows to run tests written in Smithy against your own implementation of protocols. This will be useful for third-party libraries that implementsimpleRestJson(or any other http/rest like protocol), to virtually get tests for free. We don't think this module had any users so far, but we'll slowly be porting some of our tests away from thesmithy4srepository and into thealloyrepository.
It is now possible to quickly stub a service with a default value (IO.stub being a good candidate), which can be helpful for testing purposes. The resulting code looks like this :
import smithy4s.hello._
import cats.effect._
val stubbedHelloWorld: HelloWorldService[IO] = new HelloWorldService.Default[IO](IO.stub)smithy4s.Transformation has been revised to facilitate the integration with various shapes of transformations. It allows, in particular, to transform a service implementation by applying generic (but polymorphic) behaviour in all of its methods. For instance, this can be used to apply a timeout on all of the methods of a service, or retrying behaviour, etc ...
In particular, the smithy4s.Transformation companion object contains in particular AbsorbError and SurfaceError interfaces that developers can leverage to get their services to go from mono-functor (where all errors are treated as Throwable) to bi-functor (where errors are surfaced on a per-endpoint basis, forcing the developers to handle them one way or another), and vice-versa.
The generated code now contains bi-functor-specialised ErrorAwaretype-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as EitherT or ZIO.
Adds the ability to have smithy4s-level middleware that is made aware of the Server and Endpoint for use in creating middleware implementations. This unlocks creating middleware that is aware of the Smithy traits (Hints in smithy4s) and shapes in your specification. This means the middleware can apply transformations based on traits applied in a Smithy specification and it can return error responses defined in the Smithy specification. An example of this is authentication. You are now able to create middleware that will check authentication on only the endpoints that require it AND you can return a smithy-defined error response when the authentication is not valid. See the endpoint specific middleware guide for more.
Streamlines and improves how error responses are mapped to their corresponding smithy4s-generated types. It now works such that IF no X-Error-Type header is found AND the status code doesn't map precisely to an error annotated with @httpCode AND exactly one error happens to have @error("client") without @httpCode, that error will be selected (provided the status code is in the 4xx range). Same for @error("server") and 5xx range. See the error handling documentation for more.
Previously, smithy4s's HttpEndpoint was limited to supporting just a small subset of HTTP methods (POST, GET, PATCH, PUT and DELETE). This is now mitigated, and all other methods are accepted by HttpEndpoint, by means of an open-enumeration.
In order to mitigate known security problems, our json parsing logic has hard-limits over the number of elements it will parse from arrays or maps, resulting in an error when receiving payloads with larger collections. Previously, this limit was hardcoded to 1024 elements per collection. This is now configurable, 1024 being the default.
Refinements applied on list/map shapes can now produce parameterised types. This allows, for instance, to have generic
refinements on list shapes that produce cats.data.NonEmptyList containing the same types of elements.