From f6d01a0e051668ed1b377c7cedb6287be1bb5f4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20M=C3=A9lois?= Date: Wed, 23 Nov 2022 19:47:20 +0100 Subject: [PATCH 01/14] 0.17.0 Changelog draft [skip ci] --- CHANGELOG.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..f959adcf0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,65 @@ +# 0.17.0 + +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 brining inter-operability with other tools that Disney Streaming is putting forward to reinforce the Smithy ecosystem, such as [smithy-translate](https://github.com/disneystreaming/smithy-translate/). + +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. + +## Breaking changes + +### Smithy-level breaking changes + +See https://github.com/disneystreaming/smithy4s/pull/561 + +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](https://github.com/disneystreaming/alloy). + +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`. + +### Build-plugins breaking changes (SBT/mill) + +#### Multiple input directories + +See https://github.com/disneystreaming/smithy4s/pull/587 + +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 + +#### Change in smithy-library dependency resolution + +See https://github.com/disneystreaming/smithy4s/pull/607 + +We've changed the smithy-sharing mechanism to do two things : + +1. By default, any dependency declared "normally" in SBT or mill, by means or `libraryDepedencies ++=` or `def 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 `% Smithy4s` or `def smithy4sIvyDeps` : these are now reserved for libraries containing Smithy files that you **do not want your application's runtime to depend on**. +2. 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 `% Smithy4s` in SBT or `def smithy4sIvyDeps` in 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](https://github.com/disneystreaming/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. + +### Normal-usage breaking changes in the generated code + +See https://github.com/disneystreaming/smithy4s/pull/599 + +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. + +### Normal-usage source breaking changes + +See https://github.com/disneystreaming/smithy4s/pull/569 + +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 deprecated, in favour of the `SimpleRestJsonBuilder` construct (which now works for any `service` smithy shape that will have been annotated with `alloy#simpleRestJson`). + +### Advanced usage breaking changes + +The abstractions that the generated code implements and that the runtime interpreters use have undergone some massive chances. + +#### Unification of the natural-transformations/polymorphic functions. + +* Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the `project/Boilerplate.scala` file) to ensure the consistency of the various ways they are being used. This means that `smithy4s.PolyFunction` has moved to `smithy4s.kinds.PolyFunction`, and that the previous `smithy4s.Transformation` is now `smithy4s.kinds.PolyFunction5`. This decision ripples in the `smithy4s.Service` interface, which now sports `toPolyFunction` and `fromPolyFunction` methods, allowing to turn a finally-encoded implementation into a final one. `smithy4s.kinds.PolyFunction2` is 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, one inspecting the internals of this library might see things like `Kind1[IO]#toKind5` where in was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will). +* `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied on another like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces. +* The `Service` interface takes a single `Alg` type parameter, the `Op` parameter has moved to type-member position, facilitating implicit search in some contexts (as well as the writing of some logic). +* A bunch of path-dependant type-aliases were created in the `Service` interface. +* The `compliancetest` module 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 implement `simpleRestJson` (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 the `smithy4s` repository and into the `alloy` repository. + +## User facing improvements From db1f8d29532d75b98c66532741ea54198bd33385 Mon Sep 17 00:00:00 2001 From: Jeff Lewis Date: Wed, 23 Nov 2022 12:14:59 -0700 Subject: [PATCH 02/14] add endpoint middleware and error handling to changelog --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f959adcf0..dd09cb0c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -63,3 +63,12 @@ The abstractions that the generated code implements and that the runtime interpr * The `compliancetest` module 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 implement `simpleRestJson` (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 the `smithy4s` repository and into the `alloy` repository. ## User facing improvements + +### Endpoint Specific Middleware + +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](https://disneystreaming.github.io/smithy4s/docs/guides/endpoint-middleware) for more. + + +### Error Response Handling Improvements + +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](https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/client#error-handling) for more. From 665f797e432276bc8585c5e61369d4569f94a321 Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Wed, 23 Nov 2022 21:29:06 -0500 Subject: [PATCH 03/14] CHANGELOG: typos, improvements and enum deprecation [skip ci] --- CHANGELOG.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd09cb0c7..fe4cb39b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ 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 brining inter-operability with other tools that Disney Streaming is putting forward to reinforce the Smithy ecosystem, such as [smithy-translate](https://github.com/disneystreaming/smithy-translate/). +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](https://github.com/disneystreaming/smithy-translate/) and [alloy](https://github.com/disneystreaming/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. @@ -24,22 +24,32 @@ This change implies, for instance, that any use of `smithy4s.api#simpleRestJson` See https://github.com/disneystreaming/smithy4s/pull/587 -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 +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. #### Change in smithy-library dependency resolution See https://github.com/disneystreaming/smithy4s/pull/607 -We've changed the smithy-sharing mechanism to do two things : +We've changed the smithy-sharing mechanism to do two things: -1. By default, any dependency declared "normally" in SBT or mill, by means or `libraryDepedencies ++=` or `def 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 `% Smithy4s` or `def smithy4sIvyDeps` : these are now reserved for libraries containing Smithy files that you **do not want your application's runtime to depend on**. +1. By default, any dependency declared "normally" in SBT or mill, by means or `libraryDepedencies ++=` or `def 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 `% Smithy4s` or `def smithy4sIvyDeps`: these are now reserved for libraries containing Smithy files that you **do not want your application's runtime to depend on**. 2. 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 `% Smithy4s` in SBT or `def smithy4sIvyDeps` in 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](https://github.com/disneystreaming/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. ### Normal-usage breaking changes in the generated code See https://github.com/disneystreaming/smithy4s/pull/599 -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. +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: + +```sbt +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" +) +``` ### Normal-usage source breaking changes @@ -47,7 +57,7 @@ See https://github.com/disneystreaming/smithy4s/pull/569 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 deprecated, in favour of the `SimpleRestJsonBuilder` construct (which now works for any `service` smithy shape that will have been annotated with `alloy#simpleRestJson`). +In particular, the `simpleRestJson` extension method that was added to implementations of service-interfaces generated by Smithy4s is now deprecated, in favour of the `SimpleRestJsonBuilder` construct (which now works for any `service` Smithy shape that will have been annotated with `alloy#simpleRestJson`). ### Advanced usage breaking changes From 415c43ca90c7ad0709e12596677d8935c2ce3a14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Koz=C5=82owski?= Date: Thu, 24 Nov 2022 03:57:58 +0100 Subject: [PATCH 04/14] add my changus --- CHANGELOG.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe4cb39b9..efdf2807c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,4 @@ + # 0.17.0 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. @@ -59,9 +60,11 @@ If you use Smithy4s in the ways that were previously advertised in the documenta In particular, the `simpleRestJson` extension method that was added to implementations of service-interfaces generated by Smithy4s is now deprecated, 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](https://github.com/disneystreaming/smithy4s/pull/589). + ### Advanced usage breaking changes -The abstractions that the generated code implements and that the runtime interpreters use have undergone some massive chances. +The abstractions that the generated code implements and that the runtime interpreters use have undergone some massive changes. #### Unification of the natural-transformations/polymorphic functions. @@ -82,3 +85,7 @@ Adds the ability to have smithy4s-level middleware that is made aware of the `Se ### Error Response Handling Improvements 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](https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/client#error-handling) for more. + +### Support for more HTTP methods + +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`. From 8d5d04ab0be599e0fa6fb4d84ef3fb8ab2bb0ffb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Koz=C5=82owski?= Date: Thu, 24 Nov 2022 03:59:26 +0100 Subject: [PATCH 05/14] wording --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index efdf2807c..ab5cc22ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,7 +72,7 @@ The abstractions that the generated code implements and that the runtime interpr * `kind`-specific types were created to facilitate the "lift" of constructs to the right kinds. For instance, one inspecting the internals of this library might see things like `Kind1[IO]#toKind5` where in was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will). * `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied on another like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces. * The `Service` interface takes a single `Alg` type parameter, the `Op` parameter has moved to type-member position, facilitating implicit search in some contexts (as well as the writing of some logic). -* A bunch of path-dependant type-aliases were created in the `Service` interface. +* A bunch of path-dependent type aliases were created in the `Service` interface. * The `compliancetest` module 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 implement `simpleRestJson` (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 the `smithy4s` repository and into the `alloy` repository. ## User facing improvements From a077db54d6e047463b836796012883e899bd1c61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20M=C3=A9lois?= Date: Thu, 24 Nov 2022 18:39:51 +0100 Subject: [PATCH 06/14] Add more to the changelog [skip ci] --- CHANGELOG.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ab5cc22ab..b6e790c75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ The reason for us to bring this change is to have a language specific location t 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. + ### Build-plugins breaking changes (SBT/mill) #### Multiple input directories @@ -58,7 +60,7 @@ See https://github.com/disneystreaming/smithy4s/pull/569 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 deprecated, in favour of the `SimpleRestJsonBuilder` construct (which now works for any `service` Smithy shape that will have been annotated with `alloy#simpleRestJson`). +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](https://github.com/disneystreaming/smithy4s/pull/589). @@ -66,6 +68,18 @@ Additionally, some methods that were deprecated in 0.16.x releases [have been re 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 | + #### Unification of the natural-transformations/polymorphic functions. * Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the `project/Boilerplate.scala` file) to ensure the consistency of the various ways they are being used. This means that `smithy4s.PolyFunction` has moved to `smithy4s.kinds.PolyFunction`, and that the previous `smithy4s.Transformation` is now `smithy4s.kinds.PolyFunction5`. This decision ripples in the `smithy4s.Service` interface, which now sports `toPolyFunction` and `fromPolyFunction` methods, allowing to turn a finally-encoded implementation into a final one. `smithy4s.kinds.PolyFunction2` is also a thing, and may be used in bi-functor contexts. @@ -77,15 +91,52 @@ The abstractions that the generated code implements and that the runtime interpr ## User facing improvements +### Stubs + +See https://github.com/disneystreaming/smithy4s/pull/595 + +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 : + +```scala +import smithy4s.hello._ +import cats.effect._ +val stubbedHelloWorld : HelloWorldService[IO] = new HelloWorldService.Default[IO](IO.stub) +``` + +### Transformations, including bi-functors + +See https://github.com/disneystreaming/smithy4s/pull/584 + +`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. + +### Bi-functor-specialised type aliases + +See https://github.com/disneystreaming/smithy4s/pull/584/files#diff-064c6fb10e5927021c4fdb928e68fd8594443b767c54bec7d3b4a424e087401bR26 + +The generated code now contains bi-functor-specialised `WithError`type-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as EitherT or ZIO. + ### Endpoint Specific Middleware +See https://github.com/disneystreaming/smithy4s/pull/614 + 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](https://disneystreaming.github.io/smithy4s/docs/guides/endpoint-middleware) for more. ### Error Response Handling Improvements +See https://github.com/disneystreaming/smithy4s/pull/570 + 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](https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/client#error-handling) for more. ### Support for more HTTP methods -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`. +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. + +### Configurable maximum arity during Json parsing + +See https://github.com/disneystreaming/smithy4s/pull/569 + +In order to mitigate known security problems, the 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. From 756ac7572a05cfa996c923305af43e3945655484 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20M=C3=A9lois?= Date: Fri, 25 Nov 2022 16:11:49 +0100 Subject: [PATCH 07/14] small amendment to docs [skip ci] --- modules/docs/markdown/05-design/03-services.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/docs/markdown/05-design/03-services.md b/modules/docs/markdown/05-design/03-services.md index 2328c9e9e..90fa290ce 100644 --- a/modules/docs/markdown/05-design/03-services.md +++ b/modules/docs/markdown/05-design/03-services.md @@ -125,9 +125,10 @@ What we want users to manipulate is the final-encoded version of a service: a go So we codify the duality to allow for switching from one to the other via an abstraction called `Smithy4s.Service`, which is the entry point to all interpreters. ```scala -trait Service[Final[_[_, _, _, _, _]], Initial[_, _, _, _, _]] { - def toPolyFunction[F[_, _, _, _, _,]](alg: Final[F]) : PolyFunction5[Initial, F] - def fromPolyFunction[F[_, _, _, _, _]](polyFunction: PolyFunction5[Initial, F]) : Final[F] +trait Service[Final[_[_, _, _, _, _]]] { + type Operation[_, _, _, _, _] + def toPolyFunction[F[_, _, _, _, _,]](alg: Final[F]) : PolyFunction5[Operation, F] + def fromPolyFunction[F[_, _, _, _, _]](polyFunction: PolyFunction5[Operation, F]) : Final[F] // ... } From 76e3612185c9dd821004d824c437638b6459db66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20M=C3=A9lois?= Date: Mon, 28 Nov 2022 10:36:48 +0100 Subject: [PATCH 08/14] Change WithError => ErrorAware in changelog [skip ci] --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6e790c75..973a1dc5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -115,7 +115,7 @@ In particular, the `smithy4s.Transformation` companion object contains in partic See https://github.com/disneystreaming/smithy4s/pull/584/files#diff-064c6fb10e5927021c4fdb928e68fd8594443b767c54bec7d3b4a424e087401bR26 -The generated code now contains bi-functor-specialised `WithError`type-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as EitherT or ZIO. +The generated code now contains bi-functor-specialised `ErrorAware`type-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as EitherT or ZIO. ### Endpoint Specific Middleware From d5638fd4bd39fdb9cf1259621c3d7a58205c3591 Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Mon, 28 Nov 2022 10:43:45 -0500 Subject: [PATCH 09/14] Fix typo in arity section [skip ci] --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 973a1dc5b..eedd465da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -138,5 +138,5 @@ Previously, smithy4s's `HttpEndpoint` was limited to supporting just a small sub See https://github.com/disneystreaming/smithy4s/pull/569 -In order to mitigate known security problems, the our json parsing logic has hard-limits over the number of elements it will parse from arrays +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. From 0dc955d8525b91298797d7b9a8c33a31965ed3c4 Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Mon, 28 Nov 2022 10:46:14 -0500 Subject: [PATCH 10/14] Capitalized Smithy and some `code` blocks [skip ci] --- CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eedd465da..c79152155 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ In order to achieve these improvements, we've had to break a number of things at See https://github.com/disneystreaming/smithy4s/pull/561 -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](https://github.com/disneystreaming/alloy). +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](https://github.com/disneystreaming/alloy). 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`. @@ -27,7 +27,7 @@ Note that this change, in use cases that follow our documentation, should have n See https://github.com/disneystreaming/smithy4s/pull/587 -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. +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. #### Change in smithy-library dependency resolution @@ -121,14 +121,14 @@ The generated code now contains bi-functor-specialised `ErrorAware`type-aliases. See https://github.com/disneystreaming/smithy4s/pull/614 -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](https://disneystreaming.github.io/smithy4s/docs/guides/endpoint-middleware) for more. +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](https://disneystreaming.github.io/smithy4s/docs/guides/endpoint-middleware) for more. ### Error Response Handling Improvements See https://github.com/disneystreaming/smithy4s/pull/570 -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](https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/client#error-handling) 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](https://disneystreaming.github.io/smithy4s/docs/protocols/simple-rest-json/client#error-handling) for more. ### Support for more HTTP methods From 83cec489622eaf2170e489e926094290da04b3e2 Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Mon, 28 Nov 2022 10:51:49 -0500 Subject: [PATCH 11/14] Minor typo: when vs one [skip ci] --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c79152155..d273dedc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,7 +83,7 @@ Non-exhaustive list of symbol renames : #### Unification of the natural-transformations/polymorphic functions. * Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the `project/Boilerplate.scala` file) to ensure the consistency of the various ways they are being used. This means that `smithy4s.PolyFunction` has moved to `smithy4s.kinds.PolyFunction`, and that the previous `smithy4s.Transformation` is now `smithy4s.kinds.PolyFunction5`. This decision ripples in the `smithy4s.Service` interface, which now sports `toPolyFunction` and `fromPolyFunction` methods, allowing to turn a finally-encoded implementation into a final one. `smithy4s.kinds.PolyFunction2` is 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, one inspecting the internals of this library might see things like `Kind1[IO]#toKind5` where in was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will). +* `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 like `Kind1[IO]#toKind5` where it was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will). * `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied on another like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces. * The `Service` interface takes a single `Alg` type parameter, the `Op` parameter 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 `Service` interface. From 57fa5e5a22d03e7204efd664f521c2c5a70578c4 Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Mon, 28 Nov 2022 10:57:06 -0500 Subject: [PATCH 12/14] More code blocks [skip ci] --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d273dedc6..9ff116845 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -109,13 +109,13 @@ See https://github.com/disneystreaming/smithy4s/pull/584 `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. +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. ### Bi-functor-specialised type aliases See https://github.com/disneystreaming/smithy4s/pull/584/files#diff-064c6fb10e5927021c4fdb928e68fd8594443b767c54bec7d3b4a424e087401bR26 -The generated code now contains bi-functor-specialised `ErrorAware`type-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as EitherT or ZIO. +The generated code now contains bi-functor-specialised `ErrorAware`type-aliases. Those, combined with the transformations described above, should make it easier to interop with Bi-functor constructs such as `EitherT` or `ZIO`. ### Endpoint Specific Middleware From e8533ac66f82e28cec15ba007ac6c3caf4e29131 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20M=C3=A9lois?= Date: Thu, 1 Dec 2022 14:22:41 +0100 Subject: [PATCH 13/14] Add a line to the changelog about polymorphic refinements --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ff116845..8ddd37c7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -140,3 +140,10 @@ See https://github.com/disneystreaming/smithy4s/pull/569 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. + +### Polymorphic refinements + +See https://github.com/disneystreaming/smithy4s/pull/649 + +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. From 62a12f79be7d2d2d862917039ef77173a6de259f Mon Sep 17 00:00:00 2001 From: David Francoeur Date: Thu, 1 Dec 2022 09:56:18 -0500 Subject: [PATCH 14/14] Typo in unification [skip ci] --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ddd37c7a..3e1071bbe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,7 +84,7 @@ Non-exhaustive list of symbol renames : * Smithy4s makes a lot of use of polymorphic functions of various kinds. Those are now code-generated (see the `project/Boilerplate.scala` file) to ensure the consistency of the various ways they are being used. This means that `smithy4s.PolyFunction` has moved to `smithy4s.kinds.PolyFunction`, and that the previous `smithy4s.Transformation` is now `smithy4s.kinds.PolyFunction5`. This decision ripples in the `smithy4s.Service` interface, which now sports `toPolyFunction` and `fromPolyFunction` methods, allowing to turn a finally-encoded implementation into a final one. `smithy4s.kinds.PolyFunction2` is 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 like `Kind1[IO]#toKind5` where it was previously `GenLift[IO]#λ`. We're hoping to convey meaning better, although this code is definitely still not trivial (and never will). -* `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied on another like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces. +* `smithy4s.Transformation` is now a typeclass-like construct, which expresses the fact that a construct can be applied like a function. This construct is used by the `transform` method that is generated on service interfaces, which allows to apply custom behaviour generically on all method invocations in these interfaces. * The `Service` interface takes a single `Alg` type parameter, the `Op` parameter 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 `Service` interface. * The `compliancetest` module 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 implement `simpleRestJson` (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 the `smithy4s` repository and into the `alloy` repository.