DEV Community: Lucas Fugisawa

Kotlin + gRPC: Tooling, CI/CD, and Architectural Practices

Lucas Fugisawa — Wed, 07 May 2025 22:00:00 +0000

In the previous articles of this series, we explored how to build idiomatic gRPC APIs with Kotlin from schema design using Protobuf to leveraging streams, coroutines, and Kotlin DSL builders. Now it's time to look beyond the application code.

In this article, we'll have a sneak peek on what it takes to prepare your gRPC service for production. This includes:

Observability and traceability.
Security and authentication.
Testing tools and diagnostics.
Best practices for repository structure.
CI/CD automation.
And how this fits into a DDD-oriented architecture.

This fifth article is more of a bonus and a point of attention that you should focus on if you need to implement gRPC for a production environment. Each topic mentioned here is very broad, and it is up to you to delve into each of them as needed. Also, for this reason, I will not cover code changes for the content of this article specifically.

Our focus is on scalability and maintainability. Let's explore how to structure your environment so your gRPC APIs thrive in the real world.

Observability

In REST APIs, it's common to use reverse proxies, access logs, or APM tools for insights. In the gRPC world, you need to be more intentional.

Interceptors

Interceptors allow you to intercept gRPC calls and inject cross-cutting concerns like logging, metrics, or authentication. They work similarly to middleware in web frameworks.

class LoggingInterceptor : ServerInterceptor {
    override fun <ReqT, RespT> interceptCall(
        call: ServerCall<ReqT, RespT>, headers: Metadata,
        next: ServerCallHandler<ReqT, RespT>
    ): ServerCall.Listener<ReqT> {
        val method = call.methodDescriptor.fullMethodName
        println("[gRPC] Call to method: $method")
        return next.startCall(call, headers)
    }
}

You can also hook into libraries like micrometer to expose metrics (latency, counters, histograms) to your monitoring tool.

Distributed tracing and OpenTelemetry

With multiple services interacting via gRPC, tracing request flows is crucial. OpenTelemetry is the open standard for collecting traces, metrics, and logs.

val tracer = GlobalOpenTelemetry.getTracer("note-service")
val span = tracer.spanBuilder("createNote").startSpan()
try {
    // request logic
} finally {
    span.end()
}

Use OTLP exporters to send data to Jaeger, Zipkin, Grafana Tempo, NewRelic, DataDog etc. and visualize the full call path across services.

If you don't have very complex tracing requirements, I recommend that you use the OpenTelemetry Java Agent instead of instrumenting through code. And if you need some tracing customization, you can use an OpenTelemetry Collector to process the data before sending it to your monitoring tool. By avoiding instrumentation through code, you end up with a simpler, more scalable, and less intrusive solution to observe what's happening with your application.

Security: encryption and authentication

By default, gRPC does not enforce TLS or authentication. You must explicitly configure it.

TLS: encrypting transport

gRPC uses HTTP/2 under the hood, which supports TLS natively. In production, you can use managed certificates (e.g., via ingress or cert-manager). For local development, you can configure it manually:

val creds = TlsServerCredentials.create(certChain, privateKey)
val server = Grpc.newServerBuilderForPort(443, creds)
    .addService(NoteServiceImpl())
    .build()

Authentication: via metadata headers

gRPC supports custom headers via Metadata. The common pattern is to pass a token (e.g., JWT) through the Authorization header.

class AuthInterceptor : ServerInterceptor {
    override fun <ReqT, RespT> interceptCall(...): ServerCall.Listener<ReqT> {
        val token = headers.get(Metadata.Key.of("Authorization", Metadata.ASCII_STRING_MARSHALLER))
        if (!validateToken(token)) {
            call.close(Status.UNAUTHENTICATED.withDescription("Invalid token"), headers)
            return object : ServerCall.Listener<ReqT>() {}
        }
        return next.startCall(call, headers)
    }
}

In the interceptor, validate the token, extract claims, and inject user context for downstream logic.

Repository Structure: where do `.proto` files go?

In systems with multiple services, .proto file sharing becomes a real concern. You typically choose between two options:

Monorepo (app + proto together)

Everything in one place; simple for small teams.
Easy co-evolution of contracts and services.
Harder to share across languages or services.

Dedicated proto repository

Store .proto files separately with versions and changelogs.
Services import generated artifacts or raw definitions.
Publish as binary artifacts (e.g., JAR, NPM package).

This second pattern usually promotes decoupling, better versioning, and clean reuse across the organization.

Tools for testing gRPC APIs

Testing gRPC locally doesn't have to be difficult. These tools make it straightforward:

grpcurl

Think of it as curl for gRPC. Make calls from the command line:

grpcurl -plaintext -d '{"title":"Hello"}' localhost:50051 com.fugisawa.NoteService/CreateNote

Postman

Postman now supports gRPC. You can import your .proto files or use server introspection, and test methods via a graphical interface.

CI/CD: artifact generation and compatibility guarantees

You should automate the generation and publication of your Protobuf contracts.

Build + publish

In your CI pipeline, generate and publish a reusable artifact:

./gradlew generateProto build publish

This artifact can be published to Maven, GitHub Packages, or Artifactory and consumed by other services.

Compatibility checks

buf is a powerful tool that checks for breaking changes in your .proto definitions:

buf breaking --against ./previous-version

Run this in CI to prevent merges that would break existing consumers.

Domain models and Protobuf: avoiding contract leakage

The types generated by Protobuf (like Note) are transport-level DTOs. They should not be used as your domain model.

Separate domain from transport

Design rich domain types with business semantics:

data class Note(val id: NoteId, val title: Title, val content: Content)

Then map between transport and domain:

fun Note.toProto(): NoteProto = note {
    id = this@toProto.id.value
    title = this@toProto.title.value
    content = this@toProto.content.value
}

This keeps your domain clean, testable, decoupled and independent of gRPC or any other transport layer.

Final thoughts

In this article, we explored:

How to add observability with interceptors and tracing.
How to secure gRPC with TLS and token-based authentication.
How to test APIs with grpcurl and Postman.
How to structure your repositories and CI/CD pipelines.
How to keep your domain model decoupled from your transport layer.

These practices are essential for building resilient, maintainable, and scalable gRPC APIs in real-world environments.

This is the last article in the Kotlin + gRPC series. If you want to talk and exchange experiences on this subject, contact me, and I will be happy to talk.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin + gRPC: Streaming, Deadlines, and Structured Error Handling

Lucas Fugisawa — Wed, 30 Apr 2025 22:00:00 +0000

In the previous articles of this series, we built a solid foundation: from setting up a gRPC service in Kotlin, to mastering schema design, and writing idiomatic, expressive code with Protobuf and Kotlin DSLs.

Now, we're ready to go beyond the basics into features that power real-time, reactive, and resilient APIs.

In this article, we'll explore:

How gRPC streaming works, and how to use Kotlin coroutines and Flow idiomatically.
How to handle deadlines and cancellations.
How to return and interpret structured errors using gRPC status codes and custom metadata.

These features are essential when building robust and production-grade services.

When request/response isn't enough

Until now, our gRPC calls have all followed a unary pattern, where the client sends a single request and the server replies with a single response.

But gRPC supports more than that. With streaming, you can build APIs that push data continuously, handle long-lived connections, or send multiple requests and responses within a single call.

There are three types of gRPC streaming:

Server streaming: the client sends one request and receives a stream of responses.
Client streaming: the client sends a stream of requests and gets a single response.
Bidirectional streaming: both client and server send streams of messages.

Let's see how each one works in practice using Kotlin's Flow and coroutines.

Server Streaming: one request, many responses

Imagine we want to support live updates: the client subscribes to notes with a certain tag, and the server streams back matching notes as they're created.

First, let's update our .proto file and add that new RPC:

service NoteService {
  rpc StreamNotesByTag (NoteTagFilter) returns (stream Note);
}

message NoteTagFilter {
  string tag = 1;
}

Remember that when you update the Protobuf definitions, you also need to regenerate the Kotlin code by running the generateProto Gradle task, or the protoc command we saw in the first article of this series.

In Kotlin, this generates a suspending Flow-based method:

override fun streamNotesByTag(request: NoteTagFilter): Flow<Note> { 
    return flow { // Example: mock stream of notes tagged with 'kotlin'  
        val notes = listOf(
            note { title = "Note 1"; tags += "kotlin" },
            note { title = "Note 2"; tags += "kotlin" }
        } 
        notes.forEach {
            emit(it)
            delay(1000) // simulate async delivery 
        }
    }
}

The client can collect the stream:

val tagFilter = noteTagFilter { tag = "kotlin" }
val responseFlow = stub.streamNotesByTag(tagFilter)

responseFlow.collect { note ->
    println("Received note: ${note.title}")
}

This is a powerful pattern for pushing real-time updates to clients, and thanks to Kotlin Flow, it integrates naturally with your coroutine pipeline.

Client Streaming: multiple requests, one response

Let's say a client wants to send a batch of notes in a single stream, and the server replies with a summary (e.g., how many were saved).

Let's add the .proto definitions for that:

service NoteService {
  rpc CreateNotes (stream Note) returns (NoteBatchSummary);
}

message NoteBatchSummary {
  int32 count = 1;
}

The server receives a Flow<Note>:

override suspend fun createNotes(requests: Flow<Note>): NoteBatchSummary { 
    var count = 0 
    requests.collect { note ->
        println("Saving note: ${note.title}")
        count++
    } 
    return noteBatchSummary { this.count = count }
}

And on the client side, you can send a stream using flow { ... }:

val notesFlow = flow {
    emit(note { title = "Streamed Note 1" })
    emit(note { title = "Streamed Note 2" })
} 
val summary = stub.createNotes(notesFlow)

println("Server stored ${summary.count} notes")

This is great for bulk uploads or scenarios where messages arrive incrementally.

Bidirectional Streaming: send and receive concurrently

Bidirectional streaming gives you full duplex communication, which is perfect for chat apps, collaborative editing, or real-time sync.

Let's suppose we want a functionality to share notes in real time with other users in the same group.

We'll start by defining the Protobufs for that:

service NoteService {
  rpc NoteCollab(stream Note) returns (stream Note);
}

Now, we can use that new definition to implement the logic. To keep this simple, we won't implement a complete logic for collaborative group notes. Instead, we'll implement this RPC to simply echo back each note received.


override fun noteCollab(requests: Flow<Note>): Flow<Note> = flow {
    requests.collect { receivedNote ->
        println("Received from ${receivedNote.title}: ${receivedNote.content}")
        emit(
            note {
                title = "From server: ${receivedNote.title}"
                content = "${receivedNote.content}"
            }
        )
    }
}

And on the client:

val noteFlow = flow {
    emit(note { title = "Note 1"; content = "Content 1" })
    emit(note { title = "Note 2"; content = "Content 2" })
} 
val responses = stub.noteCollab(noteFlow)

responses.collect { note ->
    println("Received: ${note.title} - ${note.content}")
}

Each side can send and receive notes independently, and all backed by non-blocking, coroutine-friendly flows.

Deadlines and cancellations

Every gRPC call can be bounded by a deadline — a time limit for how long the client is willing to wait.

In Kotlin, deadlines are passed using call options:

val stubWithDeadline = stub.withDeadlineAfter(3, TimeUnit.SECONDS) 
try { 
    val note = stubWithDeadline.createNote(
        createNoteRequest { title = "Timeout?" }
    )
} catch (e: StatusRuntimeException) { 
    if (e.status.code == Status.Code.DEADLINE_EXCEEDED) {
        println("Request timed out!")
    }
}

On the server side, when the deadline is exceeded or the client cancels, collect or emit will throw a cancellation exception.

To handle this cleanly, we just need to catch potential CancellationException:

override fun streamNotesByTag(request: NoteTagFilter): Flow<Note> = flow { 
    try { 
        while (true) {
            emit(generateNote())
            delay(1000)
        }
    } catch (e: CancellationException) {
        println("Client cancelled the stream")
    }
}

This makes it easier to free up resources when clients disconnect.

Structured error handling

By default, when something goes wrong in gRPC, you'll get a StatusRuntimeException with a gRPC status code. For example:

throw Status.NOT_FOUND
    .withDescription("Note not found")
    .asRuntimeException()

The client can catch it and inspect the code and message:

try {
    stub.getNoteById(getNoteRequest { id = "missing" })
} catch (e: StatusRuntimeException) {
    println("Error: ${e.status.code} - ${e.status.description}")
}

But for production systems, you'll often want structured error responses, with application-level codes, details, or even localized messages. To achieve this, use gRPC error metadata with StatusProto.

For example, let's define an error details message in .proto:

import "google/rpc/status.proto";
import "google/rpc/error_details.proto";

And, then, build structured errors on the server:

val errorDetail = ErrorInfo.newBuilder()
    .setReason("NOT_FOUND")
    .setDomain("noteservice.fugisawa.com")
    .build() 
val statusProto = com.google.rpc.Status.newBuilder()
    .setCode(Code.NOT_FOUND_VALUE)
    .setMessage("Note not found")
    .addDetails(Any.pack(errorDetail))
    .build() throw StatusProto.toStatusRuntimeException(statusProto)

And finally extract it on the client:

val status = StatusProto.fromThrowable(e) 
val errorInfo = status?.detailsList
    ?.mapNotNull { it.unpack(ErrorInfo::class.java) }
    ?.firstOrNull()

println("Reason: ${errorInfo?.reason}, Domain: ${errorInfo?.domain}")

This approach gives you:

Machine-readable error codes.
Human-readable messages.
Extensibility with metadata.

Implementation summary: what changed from the previous article?

As in the previous articles, all code is available in individual branches of the note-service-kotlin-gprc repository. For this article, you can check the article4-streaming branch. The error handling code is not yet available in the provided source code, and should be added soon.

Here's a quick summary of what's new:

Protobuf schema:
- Added StreamNotesByTag, CreateNotes, and NoteCollab RPCs for server, client, and bidirectional streaming.
Server implementation:
- Implemented all three streaming methods using Kotlin Flow.
Client implementation:
- Demonstrated how to collect streams using Flow.

Final thoughts

In this article, we explored:

How gRPC streaming works and how to use it idiomatically with Kotlin coroutines.
How to build real-time and interactive APIs using server, client, and bidirectional streaming.
How to use deadlines and cancellation to build responsive and efficient services.
How to model structured, expressive error responses that go beyond raw status codes.

These tools give you the building blocks to write modern, responsive, and production-ready gRPC services in Kotlin.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin + gRPC: Nesting, Composition, Validations, and Idiomatic Builder DSL

Lucas Fugisawa — Wed, 23 Apr 2025 00:47:03 +0000

In the first two articles of this series, we built our first gRPC service in Kotlin and explored the essentials of Protobuf schema design from optional and repeated fields to enums, oneof, maps, and how to evolve your schema safely.

In this article, we'll level up again and explore how to:

Compose more expressive data models using nested messages and message composition.
Write idiomatic Kotlin code using the Protobuf-generated DSL builders.
Understand what types of validations belong in your schema, and which should be handled at the application level.

Let's get into it.

Designing composite schemas

As your service grows, you'll likely need to model increasingly complex data structures. Instead of dumping all fields into a single message, Protobuf encourages a compositional approach.

Let's say we want to enrich our Note with:

An author (id, name, email),
And timestamps (created/updated).

This is a great chance to encapsulate those concerns into separate messages:

message Author {
  string id = 1;
  string name = 2;
  string email = 3;
}

message Timestamps {
  string created_at = 1;
  string updated_at = 2;
}

message Note {
  string id = 1;
  string title = 2;
  optional string content = 3;
  repeated string tags = 4;
  map<string, string> metadata = 5;
  NoteStatus status = 6;
  Author author = 7;
  Timestamps timestamps = 8;
}

This brings several benefits:

Better modularity: you can reuse Author or Timestamps elsewhere.
Clearer separation of concerns.
Cleaner and more readable .proto files.

From a Kotlin perspective, this also maps nicely into structured types that you can build and test independently.

Nesting messages (inline or not)

Sometimes, if a message is only used inside a parent, it can be convenient to nest it directly:

message Note {
  message Attachment {
    oneof source {
      string file_path = 1;
      string url = 2;
    }
  }

  string id = 1;
  string title = 2;
  Attachment attachment = 9;
}

This keeps your schema scoped and avoids polluting the top-level namespace with types that are internal to Note.

In Kotlin, the generated class will be accessible as Note.Attachment, fully usable and composable like any other message.

Writing idiomatic Kotlin with the builder DSL

The protobuf-kotlin library generates Kotlin-style DSL builders for your messages. We've used these before, but now we'll dive into more advanced and idiomatic usage patterns.

You can compose nested messages with the gRPC builders DSL in a very concise and expressive way. Take a look at this example:

val note = note {
    id = UUID.randomUUID().toString()
    title = "My composed note" 
    content = "This note uses nested messages and DSL composition" 
    author = author {
        id = "user-123" 
        name = "Lucas Fugisawa" 
        email = "lucas@fugisawa.com" 
    }
    timestamps = timestamps {
        createdAt = LocalDateTime.now().toString()
        updatedAt = LocalDateTime.now().toString()
    }
}

The note is composed using a natural composition language enabled by the gRPC builders Kotlin DSLs.

This is clean, readable, and can leverage Kotlin's scope functions (apply, let, run) to make your code more concise and expressive. For example, let's say some fields should only be set when they're available:

val maybeContent: String? = fetchContent()

val note = note {
    title = "Conditional note" 
    maybeContent?.let { content = it } 

    if (includeTags) {
        tags += listOf("grpc", "kotlin")
    } 

    if (metadata.isNotEmpty()) {
        metadataMap.putAll(metadata)
    }
}

Repeated and map fields in Protobuf are always initialized (empty by default), and Kotlin gives you a nice collection interface:

note {
    tags += listOf("protos", "modeling")
    metadataMap["source"] = "imported" 
    metadataMap["priority"] = "high" 
}

You can also clear them when needed:

note {
    clearTags()
    clearMetadataMap()
}

Again, these APIs are idiomatic and safe, and you never need to worry about null collections.

Validation: should I validate on schema or application?

A recurring design question is: what types of validation should live in the Protobuf schema, and which ones should be handled in the application code?

The answer is about separating structural vs. business validation.

✅ Schema-level validation: enforce structure

When we want to enforce structure, we handle validations by the schema itself:

Is a field required or optional? → use optional, oneof, etc.
Should only one of multiple fields be set? → use oneof.
Should a field be a list? → use repeated.
Is the value restricted to a fixed set? → use enum.

These are enforced during Protobuf message parsing and ensure that the wire format is well-formed.

message Note {
  optional string title = 1;
  oneof location {
    string folder = 2;
    string tag = 3;
  }
}

This ensures structural correctness before your business logic even runs.

❗ Application-level validation: enforce business rules

These rules depend on your domain logic:

Title must be at least 5 characters.
Author email must be valid.
Updated timestamp must not precede created timestamp.
Content length must not exceed 500 words.

These should be handled in your server (and possibly client) code:

require(note.title.length >= 5) { "Title must be at least 5 characters" }

require(note.timestamps.updatedAt >= note.timestamps.createdAt) {
    "updatedAt cannot be before createdAt" 
}

If you try to push business rules into the Protobuf schema, you'll quickly hit limitations and possibly hurt your API's flexibility.

Implementation summary: what changed from the previous article?

As I mentioned in the previous article, the source code for the scope of each article will be made available in individual branches at the note-service-kotlin-gprc repository, while HEAD on the main branch will accommodate the latest working version.

In the article, I highlighted only parts of the code that were relevant to understanding the concepts. So, here is a summary of what changed in the code, which can be checked in detail in the article3-composition-validation repository branch.

✅ Protobuf implementation:

Added Author and Timestamps message types.
Included author and timestamps fields inside Note.
Moved Attachment inside Note as a nested message using oneof for mutually exclusive fields (url vs file_path).
Updated CreateNoteRequest to allow clients to pass an Author.

✅ Server-side logic:

Dynamically sets timestamps on note creation using Clock.System.now().
Calculates and includes word count in metadataDetails.
Composes the full Note using nested builders (author { ... }, timestamps { ... }) idiomatically.

✅ Client-side logic:

Demonstrates how to build nested structures using Kotlin's builder DSL (createNoteRequest { ... }).
Uses conditional composition (tags +=, metadata["key"] = value, etc.).
Prints nested fields clearly: timestamps, author info, oneof handling for attachments.

Final thoughts

In this article, we covered:

How to build richer and more structured Protobuf schemas with composition and nesting.
How to write idiomatic Kotlin using the DSL builders generated by protobuf-kotlin.
How to compose messages conditionally and fluently.
When to validate at the schema level, and when to leave it to your app logic.

These are foundational skills for writing maintainable, expressive, and production-ready gRPC services.

Next up, we'll explore a new dimension: gRPC Streaming in Kotlin, including how to build reactive APIs with coroutines and Flows — perfect for real-time updates and sync.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin + gRPC: Enhance Protobuf schema design with Optional, Repeated, Maps, Enums, Oneof and backwards compatibility

Lucas Fugisawa — Wed, 16 Apr 2025 12:03:13 +0000

In the previous (first) article of this series, we introduced gRPC and Protocol Buffers by building a minimal Kotlin gRPC service: a simple NoteService that allowed creating and retrieving notes.

Now that we've covered the fundamentals and the codebase setup, it's time to dig a bit deeper into the backbone of any gRPC application: your schema.

Protobuf is a schema-first system. Every API you design begins with a .proto file, and that file is your contract. The way you design your fields (how you think about presence, defaults, repetition, optionality, maps, enums, and even deletions) will determine how flexible and resilient your API is as it evolves. Other more architecture-level aspects (such as security, decoupling the domain model from the transport model, etc.) also affect your gRPC API resilience. However, we'll look at these later.

This article focuses on the essential building blocks of schema design:

Understanding field presence and default values.
Using optional, repeated, map, enum, and oneof effectively.
Applying best practices for evolving your Protobuf definitions without breaking clients.

Along the way, we'll evolve our NoteService use case with new requirements, applying these concepts in a real-world context.

Evolving our use case: Notes with metadata and updates

In the previous article, a note had only a title and content, and a unique id assigned on creation. That was fine as a starting point, but real-world applications rarely stay that simple.

Let's say our team now needs the following:

Notes should support optional tags, stored as a list.
Users should be able to attach custom metadata (like a map of key/value labels).
A note can optionally be marked as archived, and later we may add more status values.
We want to support partial updates, where clients can update only specific fields.
Notes may support multiple attachment types, but only one per note.

This isn't just scope creep. It's a chance to apply schema design best practices and show how to evolve your API safely and clearly.

Understanding field presence and default values

One of the developers' first challenges when using Protobuf is grasping how it handles missing vs. default values.

In Protobuf, every field has a default value based on its type. For example:

int32 defaults to 0
string defaults to ""
bool defaults to false

But here's the tricky part: unless you explicitly tell Protobuf to track field presence, you cannot distinguish between "unset" and "default".

Imagine this field:

string content = 2;

If a client omits this field entirely when calling a RPC, and another client sends an empty string (""), you won't be able to tell them apart. This matters in scenarios like PATCH operations, where "clear the content" (or change it to zero) and "leave it untouched" are very different instructions. To fix this, we have a few tools.

Using `optional` in proto3 (since v3.15) to enable presence tracking

As of version 3.15, proto3 reintroduces the optional keyword to track whether a scalar (i.e., numbers, enums and strings) field was explicitly set.

message Note {
  string id = 1;
  string title = 2;
  optional string content = 3;
}

This enables Kotlin code like:

if (note.hasContent()) { 
    // Client explicitly set the field  val content = note.content
} else { 
    // Field was not set 
}

This is particularly useful for implementing update operations where presence matters. For instance, distinguishing between "remove the content" (or change it to zero) and "leave it unchanged".

Using wrapper types to enable presence tracking for scalars

Protobuf < 3.15 doesn't support presence tracking on primitive fields (like int32, bool, etc.) by default. To track presence for those, you can use Google's wrapper types, which wrap a primitive inside a message.

Here's how you define them:

import "google/protobuf/wrappers.proto";

message NoteMetadata {
  google.protobuf.Int32Value word_count = 1;
}

This introduces a layer of indirection: the word_count is now a message with a single field, value. But this indirection lets you test for presence:

if (metadata.hasWordCount()) { 
    val count = metadata.wordCount.value
}

You can do this for all scalar types: StringValue, Int32Value, BoolValue, and so on.

Because optional was reintroduced to Protobuf 3.15+, wrappers are generally obsolete, and you shouldn't need them unless you're using messages that already use them. It's a good idea to check the Proto Best Practices when designing Protobuf APIs.

Repeated fields: modeling lists

Let's say we want to support tags for a note. This is a perfect use case for repeated fields:

message Note {
  repeated string tags = 4;
}

Repeated fields always default to empty lists. On the Kotlin side, you'll work with them as immutable lists:

val tags: List<String> = note.tagsList

You can use the Kotlin builder DSL to set them:

val note = note {
    tags += "kotlin" 
    tags += "grpc" 
}

Repeated fields are safe to evolve, so you can add them any time without breaking clients.

Using `map` for representing arbitrary key-value metadata

Let's say we want to support storing user-defined metadata on a note. Think of labels like "project" -> "gRPC" or "priority" -> "high".

message Note {
  map<string, string> metadata = 5;
}

This defines a map field that becomes a Map<String, String> in Kotlin:

val metadata: Map<String, String> = note.metadataMap

Under the hood, a map is just a repeated field of key/value pairs, but Protobuf provides syntactic sugar for it.

Some caveats you should consider when using maps are:

Map keys must be scalars (string, int, etc.).
You can't track presence of individual keys — you either have the key or you don't.
Map order is not guaranteed.

Modeling finite sets with `enum`:

Let's model a note's status. We might want to distinguish between active and archived notes:

enum NoteStatus {
  UNKNOWN = 0;
  ACTIVE = 1;
  ARCHIVED = 2;
}

message Note {
  NoteStatus status = 6;
}

Two rules here are crucial:

Always define 0 as a meaningful default, usually UNKNOWN.
Avoid changing enum numeric values, since clients may have them hardcoded.

In Kotlin, Protobuf generates an enum with a fallback for unrecognized values:

when (note.status) {
    NoteStatus.ACTIVE -> ...
    NoteStatus.ARCHIVED -> ...
    NoteStatus.UNRECOGNIZED -> ...
}

This is critical for forward compatibility: if a newer server adds a new status (DELETED = 3), older clients won't crash — they'll get UNRECOGNIZED.

Handling mutually exclusive fields with `oneof`:

Let's say users can attach either a file or a URL to a note, but never both.

message Attachment {
  oneof source {
    string file_path = 1;
    string url = 2;
  }
}

This enforces exclusivity: only one of the fields can be set at a time.

Kotlin gives you a .sourceCase field to inspect:

when (attachment.sourceCase) {
    Attachment.SourceCase.FILE_PATH -> ...
    Attachment.SourceCase.URL -> ...
    Attachment.SourceCase.SOURCE_NOT_SET -> ...
}

This is a powerful modeling tool when you want a field to be either-or, such as “use X or use Y, but not both”.

Safe schema evolution

As your service evolves, you'll need to change your schema, but not all changes are safe. Protobuf allows some flexibility, but you must follow a few rules to avoid breaking existing clients or corrupting data.

Safe changes

✅ Adding new fields (with new tags): This is safe and common. Clients that don't know the new field simply ignore it. Just be sure to use a unique tag that hasn't been used before.
✅ Adding new enum values (with new tags): This is also safe. Clients that don't recognize the new value will treat it as UNRECOGNIZED, allowing fallback handling.
⚠️ Changing field names: The name of the field doesn't affect the wire format. Only the tag matters. However, generated code will change, which may break client code unless they recompile. Safe for the protocol, but not always for your code.
⚠️ Changing default behavior: While proto3 does not support custom default values in .proto files, you can change how your app behaves when a field is unset. This is safe as long as you don't rely on transmitted defaults.

Breaking changes

🚫 Removing fields: Old clients may still send these fields. If the tag is not handled properly, the data may be dropped or misinterpreted. Always reserve the tag and field name to avoid future reuse.
🚫 Changing field tags: Tags define the wire format. Changing a tag effectively creates a new field, breaking compatibility with all existing clients and servers.
🚫 Changing field types: Even similar types like int32 to int64 are encoded differently and may not deserialize correctly. Never change a field type without also changing its tag.
🚫 Reusing tag numbers: A reused tag can be misinterpreted as an old field. This is dangerous and can silently corrupt data. Always mark removed tags as reserved.

When breaking changes are truly necessary, consider versioning your messages (e.g., NoteV2) and methods (CreateNoteV2) to introduce changes without affecting existing consumers.

Type Mapping Reference

Here is a quick summary of how Protobuf types map to Kotlin:

Protobuf Type	Kotlin Type	Notes
`string`	`String`	Defaults to `""`
`int32`, `int64`, `uint32`...	`Int`, `Long`, `UInt`, etc.	Defaults to 0
`bool`	`Boolean`	Defaults to false
`optional string`	`String` + `.hasField()`	Presence tracked explicitly
`google.protobuf.StringValue`	`String?` + `.hasField()`	Wrapper, allows presence detection
`repeated string`	`List<String>`	Always present, default = emptyList
`map<string, string>`	`Map<String, String>`	Always present, default = emptyMap
`enum`	`Enum`	Has `UNRECOGNIZED` fallback
`oneof`	Field + `.case` enum	Only one field set at a time

Implementation summary: What changed from the previous article?

Protobuf schema:
- Introduced optional keyword for tracking field presence (e.g., content).
- Added a repeated string tags field to allow multiple tags per note.
- Added map<string, string> metadata to store arbitrary key-value annotations.
- Introduced a NoteStatus enum with values UNKNOWN, ACTIVE, and ARCHIVED.
- Added a NoteMetadata message that includes word_count, using a wrapper type (Int32Value).
- Introduced a oneof field in Attachment to allow attaching either a URL or file path — but never both.
Server implementation:
- Now checks for presence using hasContent().
- Dynamically computes and returns word count in metadataDetails.
- Maps all new fields from the request into the response.
Client implementation:
- Demonstrates how to build a request with optional fields, tags, metadata, attachment, and enum values.
- Shows how to check presence, handle oneof, and interpret server responses idiomatically in Kotlin.

Final thoughts

Designing Protobuf schemas is more than just writing .proto files. It's about thinking deeply about how your API will evolve, how your data behaves over the wire, and how clients will interpret what they receive.

In this article, we've explored:

Why field presence matters, and how to track it.
How to use optional fields, wrapper types, repeated values, maps, and enums effectively.
How to model exclusive choices using oneof.
How to evolve your schema safely, without breaking existing clients.

These tools and techniques are foundational for any team using gRPC in production. Schema design is API design, and mastering it gives you a long-term edge in building reliable services.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin + gRPC: Build your first service in four steps

Lucas Fugisawa — Fri, 11 Apr 2025 01:20:31 +0000

This is the first article in a hands-on series where we'll explore how to build gRPC services using Kotlin. The series is designed to help you understand not only the technical how-to, but also the design choices behind Protocol Buffers and gRPC. We'll start simple and gradually introduce more advanced concepts as we go.

Here is what you can expect from the upcoming articles:

In the next article, we will explore field presence, repeated, maps, enums, oneOf, and how to evolve your API safely.
Then, we will expand our model to cover nesting, composition, validations, and idiomatic builder DSL.
Later, we will explore gRPC streaming to build APIs that go beyond request/response, using Kotlin coroutines and flows. We'll also explore deadlines and error handling.
Finally, as a bonus, we'll go over topics you should focus on if you need to implement gRPC for a production environment, like tooling, CI/CD and Architectural Practices.

By the end of the series, you will have a solid understanding of gRPC in Kotlin, and a real working service you can build upon.

If you've worked with REST APIs, you know they've become the standard way to build and expose web services. They're simple, flexible, and have broad tooling support. But when services need to communicate with each other efficiently, especially in a distributed or high-performance system, gRPC is often a better choice.

In this first article, we will talk about what gRPC is, how it fits into a Kotlin ecosystem, and how to build a simple gRPC service and client from scratch. We will also compare it to REST and JSON, discuss its tradeoffs, and walk you through the tools and structure needed to get started.

By the end, you'll understand how gRPC works, why it matters, and how to implement a basic service using Kotlin, Protocol Buffers, and gRPC.

What is gRPC and why use it?

gRPC is a framework created by Google for making remote procedure calls (RPC). It allows you to call methods on a service running on another machine as if they were local. Under the hood, it uses HTTP/2 and Protocol Buffers (Protobuf) for communication.

Protocol Buffers are a language-neutral, platform-neutral mechanism for serializing structured data. You define your messages and services in a .proto file, and code is generated from that file in your target language.

This allows for benefits such as:

Strongly typed contracts between services.
Code generation avoids boilerplate and reduces errors.
Binary serialization for performance and smaller payloads.
HTTP/2 enables multiplexing, streaming, and low latency.

REST vs. gRPC: Tradeoffs

It's important to understand that gRPC is not always "better" than REST. It's different. Choosing between REST and gRPC depends on your context, constraints, and goals.

gRPC strengths:

More efficient data transmission (Protobuf is binary, smaller than JSON).
Strong typing and codegen reduce runtime errors.
Supports streaming (one-way and bidirectional).
Easier evolution with schema compatibility rules.

REST strengths:

Human-readable and debug-friendly (JSON over HTTP).
Better support for web clients and public APIs.
Mature ecosystem, including caching, proxies, and tools.

Our Use Case: A simple Note service

In this series, we will build a Note Service — something like a backend for a basic note-taking app. Over time, we will introduce complexity gradually.

Here's what you'll see in future articles:

Add support for tags, users, and note metadata (nested fields, repeated fields).
Handle optional fields and versioning concerns as the schema evolves.
Use streaming for features like syncing or watching updates in real-time.
Learn about Protobuf features like oneof, field presence, and default values.

Let's start small: a service to create a new note with a title and content.

Project structure and tools

To build our Kotlin gRPC service, we'll use:

Kotlin/JVM as our programming language on the JVM platform.
Gradle (Kotlin DSL) — dependency and build management.
Protocol Buffers (.proto) — our API schema.
protoc — the Protobuf compiler.
gRPC Kotlin — gRPC support for Kotlin and coroutines.

Our folder structure will start with something like this (a very basic Kotlin + Gradle project), but might evolve as we expand our project scope:

note-service-kotlin-gprc/
├── build.gradle.kts
├── settings.gradle.kts
├── src/
│   ├── main/
│   │   ├── kotlin/            # Kotlin code (server + client)
│   │   └── proto/             # Protobuf files (.proto)

The source code for the scope of each article will be made available in individual branches at the note-service-kotlin-gprc repository, while HEAD on the main branch will accommodate the latest working version.

The specific branch for this article is article1-first-service.

Step 1: Writing your first `.proto` file

Let's define the initial structure of our Note Service using Protocol Buffers. This file describes the types and service methods that gRPC will generate for us.

Create a file at src/main/proto/note_service.proto with the following content:

syntax = "proto3";

package com.fugisawa.grpc.noteservice;

option java_package = "com.fugisawa.grpc.noteservice";

option java_multiple_files = true;

service NoteService { 
    rpc CreateNote (CreateNoteRequest) returns (Note); 
}

message CreateNoteRequest { 
    string title = 1; 
    string content = 2;
}

message Note { 
    string id = 1; 
    string title = 2; 
    string content = 3; 
}

Let's break this down:

`syntax = "proto3";`

This declares that we're using proto3, the most recent version of 'the Protocol Buffers language. It simplifies the syntax and sets some defaults (like making fields optional).

`package note;`

This is the Protobuf package name. It groups related messages and services under a common namespace to avoid naming conflicts.

`option java_package` and `java_multiple_files`

These are used by the code generator for JVM languages (like Kotlin or Java):

java_package = "com.fugisawa.noteservice": sets the package name in the generated Kotlin/Java code.
java_multiple_files = true: instead of placing all generated types into a single file, this generates one file per message/service, which is cleaner and more modular.

The `service` block

This defines the gRPC service and its RPC methods. In our case...

service NoteService {
    rpc CreateNote (CreateNoteRequest) returns (Note);
}

... defines a service named NoteService with one RPC method CreateNote, which accepts a message of type CreateNoteRequest and returns a Note.

gRPC will generate both a base server class and a client stub for us, based on this.

The `message` blocks

These define structured data for the request and response types.

message CreateNoteRequest {
    string title = 1;
    string content = 2;
}

This defines the input type for our CreateNote method. It has two fields: title (a string field with tag 1) and content (another string field with tag 2).

And this...

message Note {
    string id = 1;
    string title = 2;
    string content = 3;
}

... is the response type, which includes id (a string representing the unique note ID, with tag 1), title (for the note title with tag 2) and content (for the note content with tag 3).

But what are those numbered tags?

Each field in a Protobuf message has a unique number. These numbers are used in the binary encoding of the message, not the field names. They matter a lot:

Must not change once published — they define the wire format.
Can't reuse deleted field numbers — unless you're absolutely sure they won't be interpreted by old clients.
Field order doesn't matter in the source, but tags must be unique.

Protobuf tags must be between 1 and (2²⁹ - 1), but you should use 1–15 for frequently-used fields, since they encode more efficiently.

Step 2: Generating Kotlin code from Protobuf definitions

The next step is to generate Kotlin code from our .proto file. There are two main ways to do this:

Option 1: Using Gradle

For compiling our Protobuf definitions to Kotlin code, we can use a Gradle plugin, which makes our life easier. Add the Protobuf plugin and dependencies to your build.gradle.kts. Remember we also need to add the Kotlin Coroutines dependency:

plugins { 
    kotlin("jvm") version "1.9.22" 
    id("com.google.protobuf") version "0.9.4" 
}

repositories { 
    mavenCentral() 
}

dependencies { 
    implementation("io.grpc:grpc-kotlin-stub:1.4.1")  
    implementation("io.grpc:grpc-netty-shaded:1.71.0")  
    implementation("io.grpc:grpc-protobuf:1.71.0")
    implementation("com.google.protobuf:protobuf-kotlin:4.30.2")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
}

protobuf {  
    protoc {  
        artifact = "com.google.protobuf:protoc:4.30.2"  
    }  
    plugins {  
        create("grpc") {  
            artifact = "io.grpc:protoc-gen-grpc-java:1.71.0"  
        }  
        create("grpckt") {  
            artifact = "io.grpc:protoc-gen-grpc-kotlin:1.4.1:jdk8@jar"  
        }  
    }  
    generateProtoTasks {  
        all().forEach {  
            it.builtins {  
                create("kotlin")  
            }  
            it.plugins {  
                id("grpc")  
                id("grpckt")  
            }  
        } 
    }
}

(Consider using local String variables for dependency version numbers. I didn't do it here for simplicity.)

Now run:

./gradlew generateProto

This generates Kotlin and gRPC code under build/generated.

Option 2: Manual compilation using `protoc`

You can also generate code manually:

protoc  
    --proto_path=src/main/proto  
    --kotlin_out=build/generated/source/proto/main/kotlin  
    --grpc-kotlin_out=build/generated/source/proto/main/kotlin  
    note_service.proto

You'll need the protoc binary and the protoc-gen-grpc-kotlin plugin installed on your system.

Step 3: Implementing the gRPC Server

Now that we have the Kotlin stub code generated, the next step is to write the backend logic that will handle incoming gRPC calls. This is where we implement the NoteService.

package com.fugisawa.noteservice  

import com.fugisawa.grpc.noteservice.CreateNoteRequest  
import com.fugisawa.grpc.noteservice.Note  
import com.fugisawa.grpc.noteservice.NoteServiceGrpcKt  
import com.fugisawa.grpc.noteservice.note  
import java.util.*  

class NoteServiceImpl : NoteServiceGrpcKt.NoteServiceCoroutineImplBase() {  
    override suspend fun createNote(request: CreateNoteRequest): Note {  
        // Here, you will implement your note creation logic, persist the new note etc.  
        // Let's just generate dummy note, for this example:  
        val newNoteId = UUID.randomUUID().toString()  
        return note {   
            id = newNoteId  
            title = request.title  
            content = request.content  
        }  
    }  
}

In this code, what we are doing is:

We are extending the NoteServiceCoroutineImplBase (generated by the Protobuf compilation).
We are implementing the createNote() function with our own logic for creating notes.

We also need to start our gRPC server, register the service, and block the main thread (which, for simplicity, we'll do in the main application entry point function):

package com.fugisawa.noteservice  

import io.grpc.Server  
import io.grpc.ServerBuilder  

fun main() {  
    val server: Server = ServerBuilder  
        .forPort(50051)  
        .addService(NoteServiceImpl())  
        .build()  

      server.start()  
      println("Server started on port 50051")  
      server.awaitTermination()  
}

That's all we need to get a Kotlin gRPC server running.

Step 4: Creating a gRPC Client in Kotlin

Now, let's now write a client that connects to the server and sends a CreateNote request.

Typically, we will not implement a gRPC client for a gRPC service available in the same application. We will do this in this article just to keep things simple and avoid having to create a new application to act as the client.

package com.fugisawa.noteservice  

import com.fugisawa.grpc.noteservice.NoteServiceGrpcKt.NoteServiceCoroutineStub  
import com.fugisawa.grpc.noteservice.createNoteRequest  
import io.grpc.ManagedChannelBuilder  
import kotlinx.coroutines.runBlocking  

fun main() = runBlocking {  
    val channel =  
        ManagedChannelBuilder  
            .forAddress("localhost", 50051)  
            .usePlaintext()  
            .build()  

    val stub = NoteServiceCoroutineStub(channel)  

    val request = createNoteRequest {  
        title = "My first note"  
        content = "This is my first note created with gRPC!"  
    }  

    val note = stub.createNote(request)  

    println("Note created: ${note.id} - ${note.title}")  
}

This small program connects to our gRPC server and calls the CreateNote method, just like a real client would. Let's walk through what each part is doing.

We wrap our main function in runBlocking because gRPC Kotlin uses suspend functions for all RPC calls, which means we need a coroutine scope to call them.

fun main() = runBlocking { ... }

Then, we create a gRPC channel (which is a connection to the server). We are connecting to localhost:50051, which is where our server is running. We are using .usePlaintext() to disable TLS (which is fine for local development), as we didn't configure TLS for the server.

Then we create a stub. A stub is a client-side object that lets you call remote methods as if they were local. We're using the coroutine-based version, auto-generated by the gRPC Kotlin plugin.

val stub = NoteServiceCoroutineStub(channel)

This stub exposes suspend functions like createNote() that we can call directly.

The next thing we do is create a CreateNoteRequest object using the Kotlin DSL builder generated from the .proto file. This DSL-style builder only works because you're using the protobuf-kotlin library and configured our Gradle setup to generate kotlin output.

val request = createNoteRequest {
    title = "My first note"
    content = "This is my first note created with gRPC!"
}

Finally, here is where the actual RPC call happens. We call createNote() on the stub, passing the request. It suspends while the request is sent and response is received from the server.

val note = stub.createNote(request)

Notice how simple and idiomatic calling a gRPC service can be in Kotlin:

All calls are suspending functions — no callbacks, no threads to manage.
Messages are constructed using type-safe Kotlin builders.
Communication is binary, efficient, and strongly typed.

How to run the Server and the Client

We're building both server and client in the same Gradle project, but typically they would be two separate applications. In this article, we will use them by starting our application with different entry points.

To run the server, execute Server.main().
In a second terminal (or a new IntelliJ run configuration), run Client.main().

Final thoughts

In this article, we covered:

What gRPC and Protobuf are, and why they matter.
When to use gRPC vs REST.
How to define an API using a .proto file.
How to generate Kotlin code using Gradle and protoc.
How to implement and run a gRPC server and client in Kotlin.

In the upcoming articles, we'll dig deeper into optional fields, field/argument presence detection, repeat, map and oneof fields, and the subtle but important differences in how Protocol Buffers handle missing or default values. That's where things get interesting and real-world.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Scope Isolation in Kotlin DSLs with @DslMarker

Lucas Fugisawa — Sat, 05 Apr 2025 14:32:32 +0000

In the previous article Taking Kotlin Builders to the Next Level: A Type-Safe DSL Approach, we explored how Kotlin's type-safe builders allow you to build expressive and concise DSLs. But as soon as your DSL starts nesting structures, something sneaky can happen: receiver conflicts.

Let's take a deeper look at this problem and how Kotlin's @DslMarker annotation solves it, making your DSLs safer and more robust.

But if you haven't read that previous article yet, I strongly recommend you to pause here for a while and do it first.

So what's the problem, in fact?

When you nest multiple DSL blocks, like this...

val car = car {
    make = "Honda"
    model = "Civic"
    announcementDate = localDate {
        year = 2025
        month = 2
        day = 15
    }
}

..., you're creating nested lambdas with receivers, which are also closures.

In Kotlin, lambdas are closures: they carry with them access to everything in the outer scope, including the outer receiver (CarBuilder). So inside the localDate { ... } block, the compiler sees both LocalDateBuilder and CarBuilder in scope. That means inside the localDate { ... } block, you still have access to the outer CarBuilder, even though you're writing in the context of LocalDateBuilder. And that can get dangerous fast.

This can lead to subtle and unintended behavior:

announcementDate = localDate {
    make = "Oops" // Refers to CarBuilder, not LocalDateBuilder
}

The make property is not part of LocalDateBuilder, but since the lambda captures the outer receiver (CarBuilder), it's still accessible. That’s a classic receiver conflict.

What if both builders have some properties with the same name?

Let's say, hypothetically, that both CarBuilder and LocalDateBuilder define a property called year. This is not unrealistic — maybe CarBuilder tracks the model year, while LocalDateBuilder builds the date when that car model was first announced.

class CarBuilder {
    var make: String = "N/A"
    var model: String = "N/A"
    var year: Int = 0 // Model year!
    var announcementDate: LocalDate? = null
    ...
}

class LocalDateBuilder {
    var year: Int = 1970
    var month: Int = 1
    var day: Int = 1
    ...
}

Now let's write a nested DSL block:

val car = car {
    make = "Toyota"
    model = "Corolla"
    year = 2023 // OK: CarBuilder.year

    announcementDate = localDate {
        year = 2025 // Is this LocalDateBuilder.year or CarBuilder.year?
    }
}

Surprisingly, both year properties are accessible inside the localDate block. This makes the code ambiguous and error-prone, because:

If year = 2025 targets the outer receiver, the LocalDate may be built with a default year (1970), leading to silent bugs.
The code looks correct, and it compiles - but it does an unexpected thing.

If you want to be sure you're writing to the intended scope, you can always disambiguate manually using this:

announcementDate = localDate {
    this.year = 2025 // Clearly refers to LocalDateBuilder.year
    this@car.year = 2023 // Explicitly refers to CarBuilder.year
}

But of course, this adds verbosity and cognitive overhead. Using @DslMarker gives you a safer default: the compiler protects you from accidental access.

How `@DslMarker` solves this?

By annotating both CarBuilder and LocalDateBuilder with the same @CarDsl, Kotlin will restrict visibility to only the closest receiver within each block. That marker tells the compiler: these receivers belong to the same DSL, don't mix them up.

First, we need to define a DSL marker annotation:

@DslMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE)
annotation class CarDsl

Then, we need to annotate our builders using our new DSL marker annotation:

@CarDsl
class CarBuilder {
    var make: String = "N/A"
    var model: String = "N/A"
    var announcementDate: LocalDate? = null

    fun build(): Car = Car(make, model, announcementDate)
}

@CarDsl
class LocalDateBuilder {
    var year: Int = 1970
    var month: Int = 1
    var day: Int = 1

    fun build(): LocalDate = LocalDate.of(year, month, day)
}

Now, if we accidentally try this...

announcementDate = localDate {
    year = 2025
    model = "Oops" // ❌ Error: model is from CarBuilder, not in scope here
}

..., Kotlin will refuse to compile, forcing you to stay inside the intended builder scope. This helps eliminate bugs before they happen,

But… what if I really need to access the outer scope?

While @DslMarker intentionally hides outer receivers to avoid accidental misuse, Kotlin still gives you an escape hatch: you can explicitly reference outer receivers using labeled lambdas.

This is helpful in advanced use cases where you genuinely need access to both scopes, but want to do it on purpose.

Let's say you want to configure both the LocalDateBuilder and the outer CarBuilder inside the same nested block:

val car = car {
    make = "Toyota"
    model = "Corolla"
    year = 2023

    announcementDate = localDate {
        year = 2025
        month = 2
        day = 15

        make = "Oops" // not allowed due to @DslMarker
        // To access the CarBuilder.make, use  the labeled receiver explicitly
        this@car.make = "Toyota (revised)"
    }
}

And, if you have nested builders of the same type, which can cause confusion when using the default labels, you can use custom labels to make it clearer:

val car = outerCar@car {
    // ...

    announcementDate = localDate {
       // ...
        this@outerCar.make = "Toyota (revised)"
    }
}

Here's what's happening:

We've labeled the outer car block with outerCar@ (or used the implicit default @car label name)
Inside localDate { ... }, the CarBuilder is no longer directly visible (because of @DslMarker)
But we can still access it with this@outerCar (or with the default @car) explicitly referring to the outer receiver.

Final thoughts

Using the Kotlin DSL markers lets you maintain safe defaults (no accidental access), but still gives you full control when needed. It's the best of both worlds:

Safety by default with @DslMarker
Escape hatch with labeled receivers when necessary

It's a good idea to use this sparingly — reaching across DSL scopes often indicates the logic might be better separated — but it's great to know the tool is there when you need it.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Taking Kotlin Builders to the Next Level: A Type-Safe DSL Approach

Lucas Fugisawa — Sat, 15 Feb 2025 15:39:35 +0000

You might recall my Simplifying the Builder Pattern article about using Kotlin Data Classes as a simpler version of the Builder pattern. You saw how named parameters and default values removed much of the ceremony you see in a traditional Builder. Now, I want to guide you further.

In this article, we will explore Kotlin type-safe builders (DSLs). You will learn how to create code for object construction that feels more expressive. Think of it like reading small sentences.

If you want to build objects in a clear and flexible way, this piece will walk you step by step. You will see how to write DSLs in Kotlin. Then you will create objects with code like car { ... }, which is both concise and readable.

Take what you already know about Kotlin and extend it. Let's begin and see how to go beyond data classes while keeping the same clarity.

What are function types with a receiver?

Before we build our DSL, we need a quick look at one Kotlin feature: function types with a receiver.

A function type with a receiver allows you to define a block of code that acts as if it's inside an object's scope. That means you can access the object's methods and properties without extra qualifiers. Here's a simple example:

class Printer {
    fun show(message: String) = println(message)
}

// Function type with a receiver: Printer.() -> Unit
fun usePrinter(block: Printer.() -> Unit) {
    val printer = Printer()
    printer.block()
}

fun main() {
    usePrinter {
        show("Hello from inside the Printer scope")
    }
}

Inside usePrinter { ... }, you call show() directly. That's because the block is defined as Printer.() -> Unit, so it behaves like a method on Printer. More precisely, it represents an extension function type. We'll use this idea to write our DSL for building objects.

Building on data classes with a type-safe builder

In my earlier article, we had a Car data class with properties like make, model, and year. Now we will replace year with announcementDate of type LocalDate. We will create a DSL so you can write car { ... } blocks to build Car objects. Let's start with a simple Car:

data class Car(
    val make: String = "N/A",
    val model: String = "N/A",
    val announcementDate: LocalDate? = null,
)

A type-safe builder, or a DSL, will allow us to create cars like this:

val honda = car {
    make = "Honda"
    model = "Civic"
    announcementDate = localDate {
        year = 2025
        month = 2
        day = 15
    }
}

Notice the nested localDate { ... }. That's a mini-DSL for creating a LocalDate. Let's walk through the steps.

Step 1: Write a builder class for LocalDate

Define a builder for LocalDate. Store year, month, and day, then build a LocalDate:

class LocalDateBuilder {
    var year: Int = 1970
    var month: Int = 1
    var day: Int = 1

    fun build(): LocalDate = LocalDate.of(year, month, day)
}

fun localDate(block: LocalDateBuilder.() -> Unit): LocalDate {
    val builder = LocalDateBuilder()
    builder.block()
    return builder.build()
}

This lets you call localDate { ... } and set the date parts in a small block.

Inside the LocalDateBuilder, each property (year, month, day) is a mutable field. You set them in the block passed to localDate. The build() function then transforms those fields into a LocalDate.

This pattern is flexible. You could add validation or adjust default values if you need stricter control.

Step 2: Write a builder class for Car

Next, create a builder for Car. You will keep make, model, and announcementDate as mutable fields:

class CarBuilder {
    var make: String = "N/A"
    var model: String = "N/A"
    var announcementDate: LocalDate? = null

    fun build(): Car = Car(
        make = make,
        model = model,
        announcementDate = announcementDate
    )
}

The CarBuilder holds properties that match the data class fields. In your car block, you assign values to make, model, or announcementDate.

When you call build(), it creates a Car object with whatever state you defined. This separation lets you add checks or transformations if you want more than just copying values.

Step 3: Write the DSL entry function

Lastly, define a helper function to create a CarBuilder, run the block, and return the final Car:

fun car(block: CarBuilder.() -> Unit): Car {
    val builder = CarBuilder()
    builder.block()
    return builder.build()
}

You can now write:

val civic = car {
    make = "Honda"
    model = "Civic"
}

The car(block: CarBuilder.() -> Unit) function is the entry point to your DSL. It creates a CarBuilder, then runs the given block in that builder's scope. Finally, it calls build() to return the finished Car.

You can return different implementations if needed. For example, you could add logic to decide if certain fields are valid or required.

Comparing approaches: traditional builders, data classes, and DSLs

Let's compare how you might build a Car with three different patterns:

1. Traditional builder

This often appears in Java or Kotlin code that mimics the same style.

class Car private constructor(
    val make: String,
    val model: String,
    val announcementDate: LocalDate
) {
    class Builder {
        private var make: String = "N/A"
        private var model: String = "N/A"
        private var announcementDate: LocalDate = LocalDate.of(1970, 1, 1)

        fun withMake(make: String) = apply { this.make = make }
        fun withModel(model: String) = apply { this.model = model }
        fun withAnnouncementDate(date: LocalDate) = apply { this.announcementDate = date }

        fun build(): Car = Car(make, model, announcementDate)
    }
}

// Usage
val carWithBuilder = Car.Builder()
    .withMake("Honda")
    .withModel("Civic")
    .withAnnouncementDate(LocalDate.of(2025, 2, 15))
    .build()

This pattern is clear about each property you set, but it requires a separate builder class and methods like withMake, withModel, etc.

2. Kotlin data classes with named parameters

Kotlin's data classes can replace many builder use cases thanks to named parameters and default arguments.

data class Car(
    val make: String = "N/A",
    val model: String = "N/A",
    val announcementDate: LocalDate = LocalDate.of(1970, 1, 1)
)

val carWithDataClass = Car(
    make = "Honda",
    model = "Civic",
    announcementDate = LocalDate.of(2025, 2, 15)
)

You don't need extra builder methods. You can skip arguments you don't need, thanks to default values.

3. DSL (type-safe builder)

When your object or configuration gets deeper, you might want a more expressive way to nest properties. DSLs allow you to build objects within code blocks, making them easy to read or extend.

val carWithDSL = car {
    make = "Honda"
    model = "Civic"
    announcementDate = localDate {
        year = 2025
        month = 2
        day = 15
    }
}

Each block runs with the appropriate builder scope. You don’t repeat object names, and you can nest DSL calls for related objects like LocalDate.

When your object or configuration becomes more complex, you might want a more expressive way to nest properties. DSLs let you build objects in code blocks, making them easier to read and extend. Each block runs in the correct builder scope. You don’t repeat object names, and you can nest DSL calls for related objects like LocalDate. You also gain extra flexibility because a DSL block is actual Kotlin code. That means you can do more than simple assignments. For example, you can perform validations, logging, or other conditional logic inside the builder:

// Suppose you have a function that fetches or reads car data from some file.
// This can be a placeholder for actual file IO and parsing.
// For example, you might parse JSON into a CarData object.
fun loadCarData(path: String): CarData = CarData(
    make = "Nissan",
    model = "Leaf",
    isElectric = true,
)

// A simple data class to represent the loaded car data.
data class CarData(
    val make: String,
    val model: String,
    val isElectric: Boolean,
)

// DSL-based creation of a Car with integrated IO/data loading.
val carWithDSL = car {
    println("Starting the car creation process...")

    val config = loadCarData("car_config.json")

    make = config.make
    model = config.model

    if (config.isElectric) {
        announcementDate = localDate {
            year = 2025
            month = 3
            day = 1
        }
    } else {
        announcementDate = localDate {
            year = 2025
            month = 3
            day = 31
        }
    }

    require(model.isNotBlank()) { "Model must not be blank." }

    println("Car creation block finished. Building the Car object now.")
}

What’s Happening Here:

Loading External Data: The first action inside the block is to load data using loadCarData(…). You might read from a file, fetch from an API, or query a database. Since this is just a Kotlin function call, you can do this I/O inline.
Assigning Properties Dynamically: The DSL remains flexible. After reading the external data, you use the result to decide which fields to set. This gives you a huge advantage when your configuration depends on external information or user preferences.
Domain Logic: You can branch your code and change behavior based on conditions (e.g., an electric car gets a different announcement date). Everything stays in one place, inside the DSL block, which avoids scattered logic.
Validation: Because you’re using Kotlin code, you can enforce rules and constraints (require(…)) at build time. This helps keep your final object valid, all within the DSL’s context.
Logging or Feedback: Notice that you can print logs or run other side effects. This is possible because your DSL block is just a function body. You can integrate other statements, error handling, or detailed logging as needed.

Kotlin's features enabling DSLs / type-safe builders

Named and Default Parameters: These let you call constructors in a flexible way. They also reduce the need for multiple constructors.
Function Types with a Receiver: This feature drives DSL creation. You define blocks that operate in the context of a specific object. That means you access properties and methods directly, which improves readability.

Pros of the DSLs

Natural Nesting: You can nest objects that relate to each other. For example, a car { engine { ... } } DSL can clarify how parts fit together. This nesting helps you keep code organized and shows logical groupings right inside the builder.
Readability: Each block reads like a small sentence about the object you are constructing. Instead of calling many methods in a row, you see a structured layout. Future readers can follow your logic like reading a short story about how the object is built.
Less Boilerplate: You don’t repeat the same method calls or property assignments. You only define your builder classes once. Then you write short blocks that do the configuration. This saves time, especially as your objects grow in complexity.
Type-Safe: The DSL ensures you only set valid properties. The compiler checks everything. You also get IDE support, like auto-completion. This reduces mistakes and helps you see what options are available at a glance.

Use cases examples

User profile setup

You can nest parts of a user profile:

val profile = userProfile { 
    name = "Alice" 
    age = 30 
    address { 
        street = "Main Street" 
        city = "Springfield" 
    } 
}

UI configuration

You might build a layout tree in a natural way:

val mainPanel = panel { 
    panel { 
        field { 
            label = "Email"
            type = TEXT
        }
    }
    button { label = "OK" } 
    button { label = "Cancel" } 
}

Emails or reports

You can add sections or attachments in blocks:

val weeklyReportEmail = email { 
    subject = "Weekly Report" 
    to("manager@company.com") 
    to("team@company.com") 
    body = "Here is our weekly progress..." 
}

Complex file generation

For XML or JSON, DSLs let you organize nested tags and fields with clarity.

val document = xml("catalog") { 
    element("book") { 
        element("title") { } 
        element("author") { } 
    } 
    element("book") { 
        element("title") { } 
        element("author") { } 
    } 
}

This article was originally posted to my Lucas Fugisawa on Kotlin blog, at: https://fugisawa.com/taking-kotlin-builders-to-the-next-level-a-type-safe-dsl-approach/

In each of these scenarios, DSLs help you avoid confusion when building complex structures.

A word of caution: nested builders and receiver conflicts

As your DSL grows and starts to nest deeper, you might run into a subtle issue known as receiver conflict. In Kotlin, when you define multiple builder blocks, each with its own receiver (like car { ... } and localDate { ... }), the compiler allows access to all visible receivers. That can be dangerous.

val car = car {
    make = "Honda"
    model = "Civic"
    announcementDate = localDate {
        year = 2025
        month = 2
        day = 15

        // Oops — this is from the outer CarBuilder, not LocalDateBuilder!
        make = "This will, but maybe shouldn't compile..."
    }
}

Since both builders are in scope, make = ... refers to the outer CarBuilder, not the inner LocalDateBuilder. This can lead to surprising bugs and unintended assignments.

Thankfully, Kotlin provides a solution to isolate DSL scopes and prevent this kind of issue. In the next article, we'll dive into Kotlin's @DslMarker feature, what it is, why it exists, and how to use it effectively to keep your DSLs clean, safe, and predictable.

Final thoughts

Type-safe builders (DSLs) bring a new layer of readability to your code. You maintain the simplicity of data classes, then add a more expressive syntax for your objects. You write car { ... } blocks and set properties in a natural way. Test them in your next project, and see how they simplify your object creation logic.

To explore more about Kotlin-related topics, subscribe to my newsletter at https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin Devs Brasil: Fortalecendo a Comunidade Kotlin no Brasil 🚀

Lucas Fugisawa — Tue, 27 Feb 2024 02:16:49 +0000

Hoje, quero compartilhar com vocês algo que tem ocupado minha mente e coração nos últimos tempos: a criação da Kotlin Devs Brasil, uma comunidade dedicada aos desenvolvedores Kotlin no Brasil.

Por que uma comunidade Kotlin?

A pergunta que pode estar passando pela sua cabeça é: "Por que criar uma comunidade Kotlin agora?"

Bem, Kotlin tem se tornado uma linguagem cada vez mais popular. Apesar disso, percebemos uma lacuna significativa no Brasil: a falta de um espaço onde possamos nos conectar, compartilhar e crescer juntos como desenvolvedores Kotlin.

O que esperar da Kotlin Devs Brasil?

A Kotlin Devs Brasil não é apenas mais um grupo ou fórum. É um espaço para:

Colaboração: Um espaço para pessoas trabalharem juntas em projetos, compartilhando conhecimento e melhores práticas.
Aprendizado: Desde iniciantes até veteranos, todos têm algo a aprender ou ensinar.
Oportunidades: Seja você em busca de uma nova oportunidade de carreira ou alguém procurando talentos, vem com a gente!
Eventos e Workshops: Organizaremos encontros online e, eventualmente, presenciais para fortalecer nossa comunidade.
Discussões: Um lugar para tirar dúvidas, discutir tendências e muito mais.

Por que participar?

Participar de uma comunidade como a Kotlin Devs Brasil é sobre fazer parte de algo maior, contribuir para o crescimento coletivo e encontrar pessoas que compartilham dos mesmos interesses e paixões que você.

Crescimento Pessoal e Profissional: A troca de experiências e conhecimento nos torna melhores desenvolvedores e pessoas.

Networking: Conecte-se com profissionais de todo o Brasil, abrindo portas para novas oportunidades.

Contribuição: Contribua com o crescimento da comunidade Kotlin no Brasil, ajudando a moldar o futuro da tecnologia no país.

Junte-se a nós!

Estamos apenas começando, e sua participação é fundamental para construirmos uma comunidade sólida e acolhedora. Se você ama Kotlin ou está curioso sobre a linguagem, este é o seu lugar.

👉 https://kotlinbr.dev/

Estamos ansiosos para recebê-lo(a) e crescermos juntos. Vamos fortalecer a presença de Kotlin no Brasil e mostrar o talento incrível que temos aqui. Junte-se a nós nessa jornada!

Kotlin Design Patterns: Simplifying the Observer Pattern

Lucas Fugisawa — Mon, 26 Feb 2024 10:54:21 +0000

The Observer Pattern is a behavioral design pattern where an object (the subject) maintains a list of its dependents (observers), and notifies them automatically of any state changes.

This pattern ensures that multiple objects are notified when certain state changes occur. It's widely used in implementing distributed event handling systems.

The Observer Pattern decouples the subject from its observers and allows for dynamic addition or removal of observers.

Approaches in Java

Let’s consider a weather station that notifies displays when the temperature changes. Check this Java example:

// Observer Interface:
public interface Observer {
    void update(float temperature);
}

// Subject Interface:
public interface Subject {
    void registerObserver(Observer o);
    void removeObserver(Observer o);
    void notifyObservers();
}

// Concrete Subject:
public class WeatherStation implements Subject {
    private float temperature;
    private List<Observer> observers = new ArrayList<>();

    public void setTemperature(float temperature) {
        this.temperature = temperature;
        notifyObservers();
    }

    public void registerObserver(Observer o) {
        observers.add(o);
    }

    public void removeObserver(Observer o) {
        observers.remove(o);
    }

    public void notifyObservers() {
        for (Observer observer : observers) {
            observer.update(temperature);
        }
    }
}

// Concrete Observer:
public class Display implements Observer {
    private String displayId;

    public Display(String id) {
        this.displayId = id;
    }

    public void update(float temperature) {
        System.out.println(displayId + ": Temperature updated: " + temperature);
    }
}

// Client:
public class WeatherApp {
    public static void main(String[] args) {
        WeatherStation station = new WeatherStation();
        Display display1 = new Display("Display 1");
        Display display2 = new Display("Display 2");

        station.registerObserver(display1);
        station.registerObserver(display2);
        station.setTemperature(30f);
    }
}

In this Java example, WeatherStation is the subject, and Display is an observer that updates when the temperature changes. Both displays display1 and display2 are notified (update(float temperature)) when the station temperature changes.

Functional approach in Java 8+

You can use Java 8+ functional features to simplify the Observer pattern and achive a very similar approach using functional interfaces and Java's lambda expressions.

Here’s how you can adapt the Weather Station example:

import java.util.ArrayList;
import java.util.List;
import java.util.function.Consumer;

public class WeatherStation {
    private float temperature;
    private List<Consumer<Float>> onTemperatureChangeListeners = new ArrayList<>();

    public void setTemperature(float temperature) {
        this.temperature = temperature;
        notifyTemperatureChange(temperature);
    }

    private void notifyTemperatureChange(float newTemperature) {
        onTemperatureChangeListeners.forEach(listener -> listener.accept(newTemperature));
    }

    public void onTemperatureChange(Consumer<Float> listener) {
        onTemperatureChangeListeners.add(listener);
    }
}

// Usage:
WeatherStation station = new WeatherStation();

// Registering listeners using lambda expressions:
station.onTemperatureChange(temp -> System.out.println("Display 1: Temperature updated to " + temp));
station.onTemperatureChange(temp -> System.out.println("Display 2: Temperature updated to " + temp));

// Simulating a temperature change:
station.setTemperature(30f);

In this Java example:

The WeatherStation class maintains a list of Consumer<Float> objects, which are functional interfaces in Java that can be used with lambda expressions.
The onTemperatureChange method allows registering Consumer lambda expressions that will be called when the temperature changes.
When setTemperature is called, it triggers notifyTemperatureChange, which executes all registered lambda expressions with the new temperature.

Kotlin's Approach:

Kotlin provides observer delegates feature. Delegates.observable() simplifies the observer pattern implementation for objects properties changes:

You can combine observer delegates to observe property changes and higher-order functions to register callbacks.

import kotlin.properties.Delegates

class WeatherStation {
    // Observable property with callbacks:
    var temperature: Float by Delegates.observable(0f) { _, _, newValue ->
            onTemperatureChangeListeners.forEach { it(newValue) }
    }

    // List of callbacks:
    private val onTemperatureChangeListeners = mutableListOf<(Float) -> Unit>()

    // Function to add callbacks:
    fun onTemperatureChange(listener: (Float) -> Unit) {
        onTemperatureChangeListeners.add(listener)
    }
}

// Client:
fun main() {
    val station = WeatherStation()

    // Registering callbacks:
    station.onTemperatureChange { println("Display 1: Temperature updated to $it") }
    station.onTemperatureChange { println("Display 2: Temperature updated to $it") }

    // Simulating temperature change:
    station.temperature = 30f
}

In this Kotlin implementation:

The temperature property in WeatherStation is an observable property. When it changes, all registered callbacks in onTemperatureChangeListeners are invoked.
The onTemperatureChange method allows registration of lambda expressions (callbacks) that react to temperature changes.
Clients register callbacks to WeatherStation which get executed whenever the temperature property changes.

Benefits of This Approach:

Simplicity: This approach simplifies the observer pattern by eliminating the need for interfaces and concrete observer classes.
Flexibility: It's easy to add or remove behaviors (callbacks) dynamically at runtime.
Expressiveness: Leveraging Kotlin's language features results in more readable and maintainable code.

Kotlin Features Simplifying the Observer Pattern

Higher-Order Functions and Lambdas: Enables concise observer implementation using functions (behavior) as parameters.
Delegated Properties (Delegates.observable()): Simplifies property change observation.

Final thoughts

Kotlin’s Delegates.observable() offers a concise and powerful alternative to the traditional observer pattern, especially for simple use cases. For more complex scenarios, the standard implementation is still useful and can be implemented concisely.

--
This article was originally posted to my Lucas Fugisawa on Kotlin blog, at: https://fugisawa.com/kotlin-design-patterns-simplifying-the-observer-pattern/

To explore more about design patterns and other Kotlin-related topics, subscribe to my newsletter on https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin Design Patterns: Simplifying the Proxy Pattern

Lucas Fugisawa — Tue, 20 Feb 2024 15:45:49 +0000

The Proxy Pattern is a structural design pattern in object-oriented programming. It provides a surrogate or placeholder for another object to control access to it. This pattern creates a 'proxy' object that acts as an intermediary between the client and the real object.

This pattern is useful when direct access to an object is impractical or impossible. For example: when an object is remote, expensive to create, or needs additional security.

It's widely used in software development for several key purposes. The main use cases are:

Lazy Initialization (Virtual Proxy): Delays the creation of expensive objects until necessary, saving resources.
Access Control (Protection Proxy): Manages access to an object, allowing or denying operations based on permission checks.
Remote Object Access (Remote Proxy): Represents an object in a different location, handling communication in networked applications.
Logging Requests (Logging Proxy): Records operations on an object, useful for debugging and monitoring.
Caching: Stores results of operations, returning cached data for repeated requests to enhance performance.

Let's dive into two of those use cases. In these examples, we will not consider coupling, orthogonality and best practices because we want to focus on the pattern itself.

Lazy Initialization (Virtual Proxy) example

The base classes:

Let's consider a very simple and hypothetic DatabaseQuery interface and its implementation.

The Java solution is usually like this:

interface DatabaseQuery { 
    String execute(); 
}

class RealDatabaseQuery implements DatabaseQuery {
    public String execute() {
        return "Query Result";
    }
}

In Kotlin, we would have this equivalent code:

interface DatabaseQuery {
    fun execute(): String
}

class RealDatabaseQuery : DatabaseQuery {
    override fun execute() = "Query Result"
}

The proxy class:

The following Java class allows for a lazy DatabaseQuery that will instantiate the RealDatabaseQuery only when (and if) needed - that is: when execute() is called.

class LazyDatabaseQuery implements DatabaseQuery {
    private RealDatabaseQuery realQuery = null;

    public String execute() {
        if (realQuery == null) {
            realQuery = new RealDatabaseQuery();
        }
        return realQuery.execute();
    }
}

In Kotlin, you can use lazy initialization feature to simplify the implementation of the Lazy Initialization Proxy:

class LazyDatabaseQuery : DatabaseQuery {
    private val realQuery by lazy { RealDatabaseQuery() }

    override fun execute() = realQuery.execute()
}

The lazy keyword is used for lazy initialization of RealDatabaseQuery. This ensures that RealDatabaseQuery is only created when it's first needed, adhering to the principles of the Lazy Initialization Proxy pattern.

Logging Requests (Logging Proxy) example

This proxy logs each action performed on an object. It's useful for monitoring activities, debugging, or auditing system usage.

The base classes:

Let's define an interface DataService with a method fetchData(). Wel'll also define RealDataService, a class implementing this interface, where fetchData() would fetch and return data from a data source.

public interface DataService {
    String fetchData();
    String fetchStatistics();
}

public class RealDataService implements DataService {
    public String fetchData() {
        return "Data from service";
    }
    public String fetchStatistics() {
        return "999";
    }
}

In Kotlin, we would have this equivalent code:

interface DataService {
    fun fetchData(): String
    fun fetchStatistics(): String
}

class RealDataService : DataService {
    override fun fetchData() = "Data from service"
    override fun fetchStatistics(): String = "999"
}

The proxy class:

The LoggingDataServiceProxy Java class in implements a proxy for DataService. It logs a message each time its fetchData method is called, then delegates the actual data fetching to the encapsulated DataService instance.

public class LoggingDataServiceProxy implements DataService {
    private DataService service;

    public LoggingDataServiceProxy(DataService service) { this.service = service } 

    public String fetchData() {
        System.out.println("Fetching data...");
        return service.fetchData();
    }

    public String fetchStatistics() {
        return service.fetchData();
    }
}

In Kotlin, we can make use of class delegation to easily intercept and log only the desired methods:

class LoggingDataServiceProxy(private val realService: DataService) : DataService by realService {
    override fun fetchData(): String {
        println("LOG: Fetching data...")
        return realService.fetchData()
    }
}

Kotlin's class delegation (by realService) simplifies forwarding calls while allowing override for logging.

Final Thoughts

In Kotlin, the Proxy Pattern is enhanced (or even made unnecessary) by language features like class delegation, delegated properties and lazy initialization. These features allow for more concise and expressive implementations.

--
This article was originally posted to my Lucas Fugisawa on Kotlin blog, at: https://fugisawa.com/kotlin-design-patterns-simplifying-the-proxy-pattern/

To explore more about design patterns and other Kotlin-related topics, subscribe to my newsletter on https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin Design Patterns: Simplifying the Decorator Pattern

Lucas Fugisawa — Thu, 15 Feb 2024 15:11:11 +0000

The Decorator Pattern is a flexible alternative to subclassing for extending functionality. It allows behavior to be added to individual objects without affecting the other objects from the same class.

It is particularly useful when changes are needed during runtime. Also, it's useful when subclassing would result in an exponential rise of new classes.

The pattern involves an interface, concrete implementations of this interface, and decorator classes that 'wrap' the original classes. The decorators implement the same interface and forward calls to the wrapped object, optionally adding their own behavior.

Traditional Approach in Java:

Let's consider a UserRepository interface and its implementation. We'll also have a UsernameValidator as a decorator to add validation logic.

// Interface:
interface UserRepository {  
    String get(String userName);  
    void set(String userName, String user);  
}  

// Concrete Implementation:
class UserRepositoryImpl implements UserRepository {  
    private Map<String, String> userList = new HashMap<>();  

    @Override  
    public String get(String userName) {  
        return userList.get(userName);  
    }  

    @Override  
    public void set(String userName, String user) {  
        userList.put(userName, user);  
    }  
}  

// Decorator:
class UsernameValidator implements UserRepository {  
    private UserRepository repository;  
    private static final int MAX_NAME_LENGTH = 20;  
    private static final int MIN_NAME_LENGTH = 4;  

    public UsernameValidator(UserRepository repository) {  
        this.repository = repository;  
    }  

    @Override  
    public String get(String userName) {  
        return repository.get(userName);  
    }  

    @Override  
    public void set(String userName, String user) {  
        if (userName.length() < MIN_NAME_LENGTH || userName.length() > MAX_NAME_LENGTH) {  
            throw new IllegalArgumentException("User name is not of valid length");  
        }  
        repository.set(userName, user);  
    }  
}

In this Java example, UsernameValidator adds a validation layer to UserRepositoryImpl without modifying its original code.

Notice that the method get(String userName) simply delegates to the target repository, while set(String userName, String user) first decorates (adds new functionality) and then delegates to the target repository.

This pattern allows UsernameValidator to control how and when it calls into the composed UserRepository, providing a clear structure for adding or modifying behavior.

Kotlin's Approach:

In Kotlin, we actually have two usual implementations. The first one uses composition and is similar to the Java solution. The second one uses Kotlin class delegation features that allow a simpler and more concise solution.

Decorating by Composition (like the Java solution)

Decoration by composition involves explicitly composing a class with another class it wishes to decorate, rather than using class delegation. Here's the Kotlin implementation of the UserRepository example using decoration by composition:

// Interface:
interface UserRepository {
    fun get(userName: String): String?
    fun set(userName: String, user: String)
}

// Concrete Implementation:
class UserRepositoryImpl : UserRepository {
    private val userList = mutableMapOf<String, String>()
    override fun get(userName: String) = userList[userName]

    override fun set(userName: String, user: String) {
        userList[userName] = user
    }
}

// Decorator using Composition:
class UsernameValidator(private val repository: UserRepository) : UserRepository {

    override fun get(userName: String): String? {
        return repository.get(userName)
    }

    override fun set(userName: String, user: String) {
        require(userName.length in MIN_NAME_LENGTH..MAX_NAME_LENGTH) {
            "User name is not of valid length"
        }
        repository.set(userName, user)
    }

    companion object {
        private const val MAX_NAME_LENGTH = 20
        private const val MIN_NAME_LENGTH = 4
    }
}

In this composition-based approach, the UsernameValidator class explicitly contains a UserRepository instance (repository) and uses this instance to perform the actual work. It overrides the set method to add validation logic before delegating the setting of the user to the composed UserRepository object.

Decorating by Delegation (using Kotlin class delegation)

Kotlin's features, such as class delegation, make implementing the Decorator Pattern simpler and more concise.

Using the same UserRepository example:

// Interface:
interface UserRepository {
    fun get(userName: String): String?
    fun set(userName: String, user: String)
}

// Concrete Implementation:
class UserRepositoryImpl : UserRepository {
    private val userList = mutableMapOf<String, String>
    override fun get(userName: String) = userList[userName]

    override fun set(userName: String, user: String) {
        userList[userName] = user
    }
}

// Decorator with Class Delegation:
class UsernameValidator(private val repository: UserRepository) : UserRepository by repository {

    override fun set(userName: String, user: String) {
        require(userName.length in MIN_NAME_LENGTH..MAX_NAME_LENGTH) {
            "User name is not of valid length"
        }
        repository.set(userName, user)
    }

    companion object {
        private const val MAX_NAME_LENGTH = 20
        private const val MIN_NAME_LENGTH = 4
    }
}

In Kotlin, the UsernameValidator class uses class delegation (by repository) to implement UserRepository. This delegates all calls to the provided UserRepository instance, except for the overridden set method.

Kotlin Features Simplifying the Decorator Pattern

Class Delegation: Kotlin simplifies the Decorator Pattern by allowing delegation of the interface's implementation to another object. This removes the need for explicit forwarding of undecorated methods calls.

Final Thougths

In Kotlin, the Decorator Pattern is simplified through features like class delegation, enhancing readability and reducing boilerplate code. Understanding these features allows Kotlin developers to implement design patterns in a more efficient and effective manner.

--
This article was originally posted to my Lucas Fugisawa on Kotlin blog, at: https://fugisawa.com/kotlin-design-patterns-simplifying-the-decorator-pattern/

To explore more about design patterns and other Kotlin-related topics, subscribe to my newsletter on https://fugisawa.com/ and stay tuned for more insights and updates.

Kotlin Design Patterns: Simplifying the Prototype Pattern

Lucas Fugisawa — Mon, 12 Feb 2024 12:30:15 +0000

We use the Prototype Pattern when creating new instances from scratch is more expensive than copying existing ones.

So, instead of instantiating new objects, you can have a prototype from which clones / copies are made.

Traditional Approach in Java:

In this Java example, GraphicElement represents a complex graphic element with complex initialization logic, such as loading textures, calculating geometry, etc.:

interface PrototypeCapable extends Cloneable {  
    PrototypeCapable clone() throws CloneNotSupportedException;  
}  

class GraphicElement implements PrototypeCapable {  
    private String color;  
    private List<String> points; // Represents complex geometry  
    private String texture;  
    // Getters and setters ommited.  

    public GraphicElement(String color, List<String> points, String texture) {  
        this.color = color;  
        this.points = points;
        this.texture = texture;
        if (this.texture == null) {
            this.texture = "Some complex initialization logic here (loading textures, calculating geometry, etc.)";
        }
}  

  @Override  
    public GraphicElement clone() throws CloneNotSupportedException {  
        return (GraphicElement) super.clone();  
    }  
} 

// Usage:  
List<String> initialPoints = Arrays.asList("x1", "y1", "x2", "y2");  
GraphicElement originalElement = new GraphicElement("Red", initialPoints, "BrickTexture");  
GraphicElement clonedElement = originalElement.clone();  
clonedElement.setColor("Blue");  
System.out.println("Cloned Element Color: " + clonedElement.getColor()); // Output: Blue

In this example, you can see cloning is used to create a new element clonedElement based on the existing originalElement, instead of instatiating a new object from scratch. Also, the color is changed from red to blue on the clonedElement.

Kotlin's Approach:

Kotlin allows for an efficient and concise way to implement cloning of complex objects.

data class GraphicElement(
    val color: String,
    val points: List<String>,
    var texture: String? = null,
) {
    init {
        if (texture == null) {
            texture = "Some complex initialization logic here (loading textures, calculating geometry, etc.)"
        }
    }
}

// Usage:
val initialPoints = listOf("x1", "y1", "x2", "y2")
val originalElement = GraphicElement("Red", initialPoints)
val clonedElement = originalElement.copy(color = "Blue") // Modifying color while cloning

In this Kotlin example, GraphicElement is a data class used for creating complex graphic elements. The copy method simplifies the process of cloning and modifying these elements.
Notice that the color for the clonedElement can be set / changed earlier, while copying the originalElement.

Kotlin Features Simplifying the Prototype Pattern

Data Classes: Offer an inbuilt copy method, streamlining the creation of prototype instances.
copy method: Allows changing specific properties while copying, allowing for more concise and expressive code.

Final Thougths

Kotlin's approach to the Prototype pattern showcases its efficiency and simplicity. Data classes and their built-in copy method make the cloning process straightforward, simplifying the pattern implementation while maintaining functionality.

--
This article was originally posted to my Lucas Fugisawa on Kotlin blog, at: https://fugisawa.com/kotlin-design-patterns-simplifying-the-prototype-pattern/

To explore more about design patterns and other Kotlin-related topics, subscribe to my newsletter on https://fugisawa.com/ and stay tuned for more insights and updates.

DEV Community: Lucas Fugisawa

Kotlin + gRPC: Tooling, CI/CD, and Architectural Practices

Observability

Interceptors

Distributed tracing and OpenTelemetry

Security: encryption and authentication

TLS: encrypting transport

Authentication: via metadata headers

Repository Structure: where do .proto files go?

Monorepo (app + proto together)

Dedicated proto repository

Tools for testing gRPC APIs

grpcurl

Postman

CI/CD: artifact generation and compatibility guarantees

Build + publish

Compatibility checks

Domain models and Protobuf: avoiding contract leakage

Separate domain from transport

Final thoughts

Kotlin + gRPC: Streaming, Deadlines, and Structured Error Handling

When request/response isn't enough

Server Streaming: one request, many responses

Client Streaming: multiple requests, one response

Bidirectional Streaming: send and receive concurrently

Deadlines and cancellations

Structured error handling

Implementation summary: what changed from the previous article?

Final thoughts

Kotlin + gRPC: Nesting, Composition, Validations, and Idiomatic Builder DSL

Designing composite schemas

Nesting messages (inline or not)

Writing idiomatic Kotlin with the builder DSL

Validation: should I validate on schema or application?

✅ Schema-level validation: enforce structure

❗ Application-level validation: enforce business rules

Implementation summary: what changed from the previous article?

✅ Protobuf implementation:

✅ Server-side logic:

✅ Client-side logic:

Final thoughts

Kotlin + gRPC: Enhance Protobuf schema design with Optional, Repeated, Maps, Enums, Oneof and backwards compatibility

Evolving our use case: Notes with metadata and updates

Understanding field presence and default values

Using optional in proto3 (since v3.15) to enable presence tracking

Using wrapper types to enable presence tracking for scalars

Repeated fields: modeling lists

Using map for representing arbitrary key-value metadata

Modeling finite sets with enum:

Handling mutually exclusive fields with oneof:

Safe schema evolution

Safe changes

Breaking changes

Type Mapping Reference

Implementation summary: What changed from the previous article?

Final thoughts

Kotlin + gRPC: Build your first service in four steps

What is gRPC and why use it?

REST vs. gRPC: Tradeoffs

gRPC strengths:

REST strengths:

Our Use Case: A simple Note service

Project structure and tools

Step 1: Writing your first .proto file

syntax = "proto3";

package note;

option java_package and java_multiple_files

The service block

The message blocks

But what are those numbered tags?

Step 2: Generating Kotlin code from Protobuf definitions

Option 1: Using Gradle

Option 2: Manual compilation using protoc

Step 3: Implementing the gRPC Server

Step 4: Creating a gRPC Client in Kotlin

How to run the Server and the Client

Final thoughts

Scope Isolation in Kotlin DSLs with @DslMarker

So what's the problem, in fact?

What if both builders have some properties with the same name?

Repository Structure: where do `.proto` files go?

Using `optional` in proto3 (since v3.15) to enable presence tracking

Using `map` for representing arbitrary key-value metadata

Modeling finite sets with `enum`:

Handling mutually exclusive fields with `oneof`:

Step 1: Writing your first `.proto` file

`syntax = "proto3";`

`package note;`

`option java_package` and `java_multiple_files`

The `service` block

The `message` blocks

Option 2: Manual compilation using `protoc`

How `@DslMarker` solves this?