<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Kapil Malik on Medium]]></title>
        <description><![CDATA[Stories by Kapil Malik on Medium]]></description>
        <link>https://medium.com/@kapilmalik?source=rss-4779bffd4e73------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*Yul8rWAf9kdSpBhQ.</url>
            <title>Stories by Kapil Malik on Medium</title>
            <link>https://medium.com/@kapilmalik?source=rss-4779bffd4e73------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 09:43:33 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@kapilmalik/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Injecting External Types in AWS Smithy]]></title>
            <link>https://medium.com/@kapilmalik/injecting-external-types-in-aws-smithy-b87c8c1d50fb?source=rss-4779bffd4e73------2</link>
            <guid isPermaLink="false">https://medium.com/p/b87c8c1d50fb</guid>
            <category><![CDATA[smithy]]></category>
            <category><![CDATA[scala]]></category>
            <category><![CDATA[cross-team-collaboration]]></category>
            <dc:creator><![CDATA[Kapil Malik]]></dc:creator>
            <pubDate>Sun, 25 Feb 2024 12:08:13 GMT</pubDate>
            <atom:updated>2024-02-25T12:08:13.363Z</atom:updated>
            <content:encoded><![CDATA[<p><a href="https://smithy.io/2.0/index.html">AWS Smithy</a> is an interface definition language by AWS. It can be used to define services and SDKs in multiple languages including Scala, Rust, Go etc. While the basic usage of Smithy and codegen plugins is straightforward, we provide a way to inject custom / external types in the code generated from AWS Smithy. This is an important requirement for practical adoption of Smithy as an IDL in existing projects.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vdoSk3S83HDGcXXAZWQK2Q.png" /><figcaption>Smithy with external types</figcaption></figure><h3>Basic Smithy Introduction</h3><p><strong>Smithy Model</strong></p><p>We define a Smithy model in .smithy files. Here is a simple service definition -</p><pre>$version: &quot;2.0&quot;<br><br>namespace com.kmalik.smithy.service<br><br>use smithy4s.meta#packedInputs<br><br>@packedInputs<br>service MyService {<br>    version: &quot;1.0.0&quot;,<br>    operations: [myRead, myWrite]<br>}<br><br>operation myRead {<br>    input := {<br>        @required<br>        id: String<br>    },<br>    output := {<br>        @required<br>        value: MyObject<br>    }<br>}<br><br>operation myWrite {<br>    input := {<br>        @required<br>        obj: MyObject<br>    }<br>    output := {<br>        @required<br>        success: Boolean<br>    }<br>}<br><br>structure MyObject {<br>    @required<br>    id: String<br><br>    @required<br>    data: String<br>}</pre><p>The model defines a service <em>MyService</em> and exposes read / write operations over a structure <em>MyObject</em>. While the Smithy model above is reasonably self-explanatory, you can refer to the exact details of Smithy language constructs in the official documentation.</p><p><strong>Generated Scala Code</strong></p><p>We can use <a href="https://disneystreaming.github.io/smithy4s/">Smithy4s</a> plugin for code generation. For service, the plugin generates a Scala trait <em>MyService[F[_]]</em> that uses generics. For other structures like input / output params and <em>MyObject</em>, case classes / POJOs are generated.</p><p>Here are some snippets of the generated code -</p><pre>type MyService[F[_]]<br> ...<br><br>final case class MyReadInput(id: String)<br><br>...<br><br>final case class MyObject(id: String, data: String)<br></pre><p><strong>Integrating Smithy generated code</strong></p><p>It’s then possible for clients to define <em>usable</em> interfaces for <em>MyService</em> with their choice of monads. For instance -</p><pre><br>// Service trait based on Try.<br>import scala.util.Try<br>trait MyServiceTry extends MyService[Try] {<br>  def myRead(input: MyReadInput): Try[MyReadOutput]<br>  def myWrite(input: MyWriteInput): Try[MyWriteOutput]<br>}<br><br>// similarly, we can define the trait based on cats IO or Future<br><br>// We can also define traits based on complex Monads<br><br>// Future of Try<br>import scala.concurrent.Future<br>type FutureTry[A] = Future[Try[A]]<br>trait MyServiceFutureTry extends MyService[FutureTry] {<br>  def myRead(input: MyReadInput): Future[Try[MyReadOutput]]<br>  def myWrite(input: MyWriteInput): Future[Try[MyWriteOutput]]<br>}<br><br>// IO over Either of Throwable or result<br>import cats.effect.IO<br>type IOEither[A] = IO[Either[Throwable, A]]<br>trait MyServiceIOEither extends MyService[IOEither] {<br>  def myRead(input: MyReadInput): IO[Either[Throwable, MyReadOutput]]<br>  def myWrite(input: MyWriteInput): IO[Either[Throwable, MyWriteOutput]]<br>}</pre><p>And then subsequent clients (teams / developers) can have their own implementation against these usable interfaces.</p><h3>External Types</h3><p>While Smithy is an excellent choice for defining an SDK from scratch, it can be challenging to use it in existing projects where we have a set of existing classes and traits that we want to use within the SDK.</p><p>Also, the generated code only produces a trait for the Service shape. However, every other structure — namely the input parameters and response types of an operation, are case classes and can only hold data but not define a behavior.</p><p>For example, suppose our class MyObject also has a version and a last modified timestamp.</p><pre>structure MyObject {<br>    @required<br>    id: String<br><br>    @required<br>    data: String<br><br>    @required<br>    version: Integer<br><br>    @required<br>    @timestampFormat(&quot;epoch-seconds&quot;)<br>    ts: Timestamp<br>}</pre><p>We want to define a trait <em>ConflictResolver</em> that defines a method <em>resolve</em>. For instance -</p><pre>trait ConflictResolver {<br>// returns true if the incoming object should overwrite the existing object<br>  def resolve(existing: MyObject, incoming: MyObject): Boolean<br>}</pre><p>The write method implementation would check if an object already exists in store for the given id. If so, it would use conflict resolver to decide whether the incoming object should be accepted to overwrite the existing one or not. Here is the pseudo code for how the decision would look like —</p><pre>if (existing!=null &amp;&amp; !conflictResolver.resolve(existing, input))) {<br>  throw new RuntimeException(s&quot;Conflict resolver unsatisfied for id: ${input.id}&quot;)<br>}</pre><p>Examples of a conflict resolver might be - version based (accept only objects with same or newer version to write), or timestamp based (accept only objects with newer last updated time), or any other complex business logic.</p><p>Further, it’s possible that a Conflict resolver implementation already exists in another library in the project and we want our Smithy model to incorporate that.</p><p>Now, we want our write operation to take in an instance of conflict resolver. However, the bare-bones offering from Smithy doesn’t allow that.</p><pre>operation myWrite {<br>    input := {<br>        @required<br>        obj: MyObject<br><br>        resolver: ConflictResolver (trait) --&gt; NOT ALLOWED !<br>    }<br>    ...<br>}</pre><h3>Smithy4s Type refinements</h3><p>Smithy4s offers a customization known as <a href="https://disneystreaming.github.io/smithy4s/docs/codegen/customisation/refinements">type refinements</a>. A type refinement allows to represent specific types in Smithy model with a custom scala type.</p><p>The official example by Smithy4s uses type refinement to enforce a particular format. For instance, if we have an email field of type String, we might want the value to always adhere to a particular regex format. This is how Smithy4s type refinement does it -</p><pre>// Define a custom smithy trait emailFormat that can apply on a string<br>@trait(selector: &quot;string&quot;)<br>structure emailFormat {}<br><br>// Apply the trait over the field that we want to enforce the format<br>@emailFormat<br>string Email<br><br>// Use Smithy4s refinement functionality to specify the custom <br>// scala target class for the emailFormat trait<br>use smithy4s.meta#refinement<br><br>apply test#emailFormat @refinement(<br>  targetType: &quot;myapp.types.Email&quot;<br>)</pre><p>The Scala code looks like this -</p><pre>// package myapp.types<br>import smithy4s._<br><br>case class Email(value: String)<br>object Email {<br><br>  private def isValidEmail(value: String): Boolean = ???<br><br>  def apply(value: String): Either[String, Email] =<br>    if (isValidEmail(value)) Right(new Email(value))<br>    else Left(&quot;Email is not valid&quot;)<br><br>  implicit val provider: RefinementProvider[EmailFormat, String, Email] = Refinement.drivenBy[EmailFormat](<br>    Email.apply, // Tells smithy4s how to create an Email (or get an error message) given a string<br>    (e: Email) =&gt; e.value // Tells smithy4s how to get a string from an Email<br>  )<br>}</pre><p>With the above customization, an object of type Email in Smithy model will be represented by our custom case class Email.</p><h3>Using Smithy4s Type refinement for External Traits</h3><p>We leverage the refinement customization for our <em>ConflictResolver</em> use case.</p><p>Here is the code snippet in Smithy model —</p><pre>namespace com.kmalik.smithy.refinement<br><br>use smithy4s.meta#refinement<br><br>@trait(selector: &quot;:test(member &gt; string)&quot;)<br>structure conflictResolverTag {}<br><br>// this tells to use the external scala class for this annnotation<br>apply conflictResolverTag @refinement(<br>    targetType: &quot;com.kmalik.smithy.refinement.external.ConflictResolver&quot;<br>)<br><br>operation myWrite {<br>    input := {<br>        @required<br>        obj: MyObject<br><br>// the annotation ensures that conflictResolver field <br>// is reperesented by custom scala code for ConflictResolver<br>        @conflictResolverTag<br>        conflictResolver: String<br>    }<br>    output := {<br>        @required<br>        success: Boolean<br>    }<br>}</pre><p>Here is the Scala code for <em>ConflictResolver</em> -</p><pre>package com.kmalik.smithy.refinement.external<br><br>// Refers to generated code from Smithy model<br>import com.kmalik.smithy.refinement.{ConflictResolverTag, MyObject}<br>import smithy4s.{Refinement, RefinementProvider}<br><br>// Define a trait instead of the case class !<br>trait ConflictResolver {<br>  def resolve(existing: MyObject, incoming: MyObject): Boolean<br>}<br><br>object ConflictResolver {<br><br>  def apply(value: String): Either[String, ConflictResolver] =<br>    Right((_: MyObject, _: MyObject) =&gt; true)<br><br>  implicit val provider: RefinementProvider[ConflictResolverTag, String, ConflictResolver] =<br>    Refinement.drivenBy[ConflictResolverTag](<br>      ConflictResolver.apply,<br>      (e: ConflictResolver) =&gt; e.toString<br>    )<br>}</pre><p>Here is the signature for generated <em>MyWriteInput</em> parameter -</p><pre>// The generated code itself imports the external definition in Scala<br>import com.kmalik.smithy.refinement.external.ConflictResolver<br><br>final case class MyWriteInput(<br>  obj: MyObject, <br>  conflictResolver: Option[ConflictResolver] = None)</pre><p>And voila! Our Smithy model can now take in an instance of type <em>ConflictResolver</em>, a trait that we defined externally elsewhere. This not only allows for injection of external classes, but also for additional customization as we can have different implementations for <em>ConflictResolver</em>.</p><p>Here are the custom implementations that we discussed earlier -</p><pre>class VersionBasedConflictResolver extends ConflictResolver {<br><br>  override def resolve(existing: MyObject, incoming: MyObject): Boolean =<br>  {<br>    existing.id == incoming.id &amp;&amp; existing.version &lt;= incoming.version<br>  }<br>}</pre><p>And</p><pre>class TimestampBasedConflictResolver extends ConflictResolver {<br><br>  override def resolve(existing: MyObject, incoming: MyObject): Boolean =<br>  {<br>    existing.id == incoming.id &amp;&amp; existing.ts.epochSecond &lt;= incoming.ts.epochSecond<br>  }<br>}</pre><p>This technique is not directly available in Smithy4s documentation, and it allows a great deal of flexibility in integrating Smithy with an existing set of libraries and classes.</p><p>You can find the complete code in github. Refer Smithy model in <a href="https://github.com/kapil-malik/hello-smithy/blob/main/src/main/smithy/sample-refinement.smithy">sample-refinement.smithy</a> and Scala code in <a href="https://github.com/kapil-malik/hello-smithy/tree/main/src/main/scala/com/kmalik/smithy/refinement">refinement</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b87c8c1d50fb" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>