DEV Community: AranaDeDoros

Backend template for Scala

AranaDeDoros — Mon, 23 Feb 2026 16:09:43 +0000

Something I've always found somewhat grating is setting up scala projects, so a few days ago I decided to make a template for backend projects using the Typelevel stack.

It's got a basic, pragmatic folder structure with the goal of concern separation and resource management.

Check it out

What Happens When One Parallel Call Fails? Structured Concurrency in Scala

AranaDeDoros — Thu, 12 Feb 2026 22:38:30 +0000

When building backend systems, we often fan out to multiple services in parallel:

Price providers
Recommendation engines
Search indexes
Payment gateways

The real question isn't "How do I run these in parallel?"

It's:

What happens if one fails?
What happens if one times out?
Do retries leak work?
Can I keep partial results?

I explored this while building a small price aggregation simulator in Scala 3 using Cats Effect.

The scenario

The setup was simple:

Multiple providers
Each returns a price
We call them in parallel
We aggregate the results

But the interesting part wasn't parallelism.

It was failure semantics.

The Core Abstraction

trait PriceProvider[F[_]]:
  def name: ProviderName
  def fetchPrice(productId: ProductId): F[Price]

Providers may fail.

One specific failure is modeled explicitly:

sealed trait ProviderError extends Throwable
final case class TimeOutError(provider: String,time: LocalDateTime) 
extends ProviderError(s"$provider timed out", time)

Timeouts are not transport hacks.

They are part of the domain.

Retry as a Decorator

Instead of baking retry into the provider, I wrapped providers with a retry policy:

def retryOnTimeout[A](
  fa: IO[A],
  maxRetries: Int,
  delay: FiniteDuration
): IO[A] =

  def loop(attempt: Int): IO[A] =
    fa.handleErrorWith {
      case _: TimeOutError if attempt < maxRetries =>
        IO.sleep(delay) *> loop(attempt + 1)
      case e =>
        IO.raiseError(e)
    }

  loop(0)

Then composed it:

final class RetryingProvider(
  underlying: PriceProvider[IO],
  maxRetries: Int,
  delay: FiniteDuration
) extends PriceProvider[IO]:

  override def fetchPrice(productId: ProductId): IO[Price] =
    retryOnTimeout(
      underlying.fetchPrice(productId),
      maxRetries,
      delay
    )

Important detail:

Only timeouts retry
Other failures propagate immediately
The underlying provider remains untouched

Retry is a policy layer, not embedded behavior.

Aggregation Strategy #1 — Fail Fast

def fetchAll(
  providers: List[PriceProvider[IO]],
  productId: ProductId
): IO[List[Price]] =
  providers.parTraverse(_.fetchPrice(productId))

Semantics:

All providers run in parallel
If one fails, the whole operation fails
Remaining providers are cancelled

This is strict and correct when all results are required.

Aggregation Strategy #2 — Keep Partial Results

Sometimes partial success is acceptable.

So instead of failing the entire computation, we capture results explicitly:

def fetchSafe(
  provider: PriceProvider[IO],
  productId: ProductId
): IO[ProviderResult] =
  provider.fetchPrice(productId)
    .map(price =>
      ProviderResult.Success(provider.name, price)
    )
    .handleError {
      case e: ProviderError =>
        ProviderResult.Failure(provider.name, e)
    }

Then aggregate:

def fetchAllPartial(
  providers: List[PriceProvider[IO]],
  productId: ProductId
): IO[List[ProviderResult]] =
  providers.parTraverse(p => fetchSafe(p, productId))

Now:

All providers run in parallel
Failures don't cancel siblings
Partial results are preserved
The operation always completes

Different policy. Same building blocks.

Optional: Enforcing a Quorum

You can even require a minimum number of successes:

def requireAtLeast(
  n: Int,
  results: List[ProviderResult]
): IO[List[(ProviderName, Price)]] =
  val successes = results.collect {
    case ProviderResult.Success(p, price) => (p, price)
  }

  if successes.size >= n then IO.pure(successes)
  else IO.raiseError(new RuntimeException("Not enough providers"))

Now the system supports:

Fail-fast
Partial aggregation
Quorum-based acceptance

All composed explicitly.

What This Experiment Revealed

The interesting part wasn't syntax. It was separation of concerns.

The system has three independent policy layers:

1. Failure classification (timeouts vs other errors)

2. Retry behavior (decorator)

3. Aggregation strategy (fail-fast vs partial vs quorum)

None of them are tangled together.

That's the real value.

When to retry
When to cancel
When partial results are acceptable
When to fail the whole operation

The abstraction you choose determines how clearly you can express those decisions.

And that's a backend engineering concern, not a language feature.

Using Scala to build tooling for Django

AranaDeDoros — Mon, 02 Feb 2026 06:01:25 +0000

   ____      _               ____            
/ ___|___ | |__  _ __ __ _ / ___| ___ _ __
| |   / _ \| '_ \| '__/ _` | |  _ / _ \ '_ \
| |__| (_) | |_) | | | (_| | |_| |  __/ | | |
\____\___/|_.__/|_|  \__,_|\____|\___|_| |_|

Some of the best parts of being a polyglot developer are being able to combine your favorite languages in practical ways.

At my current job, I haven’t had many opportunities to use Scala until recently. Even if I wanted to, I can’t (and shouldn’t) force my language preferences on my teammates. What I can do is build tooling that benefits everyone.

That’s usually how these projects start: small tools to make my own life easier.

We’ve been using Django quite a bit, and I found myself writing the same model boilerplate over and over. So I built Cobragen, a small CLI tool that generates a models.py file from a YAML schema definition.

Usage

Make a yaml file with your models schema, like this:

models:
  - name: UserProfile
    fields:
      - name: username
        type: Char
        maxLen: 50
        unique: true

      - name: bio
        type: TextField
        required: false

      - name: age
        type: Integer

      - name: balance
        type: Decimal
        maxDigits: 12
        places: 2

      - name: created_at
        type: DateTime

      - name: is_verified
        type: Boolean

  - name: Post
    fields:
      - name: author
        type: ForeignKey
        to: UserProfile
        onUpdate: CASCADE

      - name: title
        type: Char
        maxLen: 200

      - name: content
        type: TextField

      - name: published_date
        type: Date
        required: false

then run:

cobragen <schema.yml> [--sort] [--name <output>]

--sort — sort models alphabetically by name before generation (default: false)
--name <filename> — custom output filename (default: models.py)

This will generate a .py file with your models:

from django.db import models


class Post(models.Model):
    author = models.ForeignKey("UserProfile", on_delete=models.CASCADE)
    title = models.CharField(max_length=200)
    content = models.TextField()
    published_date = models.DateField(null=True, blank=True)

class UserProfile(models.Model):
    username = models.CharField(max_length=50, unique=True)
    bio = models.TextField(null=True, blank=True)
    age = models.IntegerField()
    balance = models.DecimalField(max_digits=12, decimal_places=2)
    created_at = models.DateTimeField()
    is_verified = models.BooleanField()

It has its lil problems, but I can live with them. It has partial feature support and covers what I currently need; it was a nice exercise in schema modeling and code generation across ecosystems.

Repo

Building a Nim library: Monika

AranaDeDoros — Tue, 27 Jan 2026 15:07:38 +0000

Recently I went through a phase of learning Nim. It was a good time, but I ultimately decided not to dwell too deep into it. This journey however spawned a microlibrary: Monika.

I started Nim on a whim because I wanted to have a system's programming language under my belt or at least native compilation, better speed and for the sake of applying what I was learning. I did C a lot of years ago, but I didn't want to deal with pointers directly and Rust syntax was a bit too much for me (even though I'm used to seeing some unsightly Scala's method signatures).

This library is actually a port from my own library JpnUtils written in Scala. It has a few extra functions that I didn't include in JpnUtils.

Monika is a Japanese strings microlibrary for Nim. It provides a clean, "implicit-style" API for handling characters, strings, and conversions.

Features

Implicit Conversions: Treat standard strings as Japanese objects via Nim converters.
Script Detection: Easily check for Hiragana, Katakana, and Kanji.
Diacritics: Detect Dakuten (voiced) and Handakuten (semi-voiced) marks.
Half-Width Conversion: Efficiently convert between full-width and half-width forms.
Punctuation Wrappers: Scala-style string wrapping for Japanese quotes.

Usage

Monika uses a converter to extend standard strings. Simply import Monika and start using the utility methods.

import monika/japaneseutils
import monika/punctuation
import monika/halfwidthconverter

if "こんにちは".hasHiragana:
  echo "Contains Hiragana!"

if "モニカ".hasKatakana:
  echo "Contains Katakana!"

if "学校".hasKanji:
  echo "Contains Kanji!"

# full-width to half-width
echo "ハロー、ワールド！".toHalfWidth
# Output: ﾊﾛｰ､ﾜｰﾙﾄﾞ!

# Check for voiced marks
if "が".hasDakuten:
  echo "This character is voiced."

let msg = "Hello"
echo msg.wrapInSingleQuotes # Output: 「Hello」
echo msg.wrapInDoubleQuotes # Output: 『Hello』

let s = "ガキ"
let h = "が".asRune()
let k = "エ".asRune()

if h.isSome:
  echo h.get.hiraToKata() # Output: カ
else:
  echo "empty string"

if k.isSome:
  echo k.get.kataToHira() # Output: え
else:
  echo "empty string"

let str = "日本語abcカナ"
echo str.containsOnly({Kanji, Katakana})  # false
let summary = str.scriptSummary()

echo summary.hiragana  # 0
echo summary.katakana  # 2
echo summary.kanji     # 3
echo summary.other     # 3

It was a good experience, but If I were to be honest; I don't see myself using Nim that much outside of really niche things and even so, I might reconsider it. Maybe I'll make a post in the future about what I don't like about the actual Nim ecosystem.

If you wanna check it out, the repo's here

Nim + FastAPI experiment

AranaDeDoros — Wed, 21 Jan 2026 14:00:00 +0000

Why use one language when you can use two?

I've been experimenting with FastAPI and Nim lately, and I decided to bridge them together to build a simple PDF merger.

The goal? Offload the possible heavy binary lifting of PDF generation to Nim (which compiles to C) while keeping the web layer comfy with Python.

Nim process:

import nimpdf
import nimpdf/image
import os
import times

proc makePDF(outputPath: string, files: seq[string]): bool =
  let factorX = 20.0
  let factorY = 200.0
  var pdf = newPDF()

  for file in files:
    block:
      discard pdf.addPage("A4")
      let img = loadImage(file)

      if img == nil:
        echo "Warning: Could not load ", file
        continue

      pdf.drawImage(factorX, factorY, img)

  return pdf.writePDF(outputPath)

when isMainModule:
  let start = cpuTime()
  if paramCount() < 2:
    quit "Usage: pdf_merger <output.pdf> <images...>", QuitFailure

  let outputPath = paramStr(1)
  var images: seq[string] = @[]
  for i in 2 .. paramCount():
    images.add paramStr(i)

  if makePDF(outputPath, images):
    let duration = cpuTime() - start
    echo "PDF created in ", duration, " seconds at ", outputPath
    quit QuitSuccess
  else:
      quit "Failed to write PDF", QuitFailure

The endpoint:

@app.post("/upload-multiple-files/")
async def create_upload_files(files: List[UploadFile] = File(...)):
    start = time.perf_counter()
    job_id = str(uuid.uuid4())
    output_filename = os.path.join(OUTPUT_DIR, f"{job_id}.pdf")

    uploaded_paths = []
    for file in files:
        unique_img_name = f"{uuid.uuid4()}_{file.filename}"
        file_path = os.path.join(UPLOAD_DIR, unique_img_name)
        with open(file_path, "wb") as buffer:
            shutil.copyfileobj(file.file, buffer)
        uploaded_paths.append(file_path)

    def run_nim():
        return subprocess.run(
            [NIM_EXE_PATH, output_filename] + uploaded_paths,
            capture_output=True,
            text=True
        )

    result = await anyio.to_thread.run_sync(run_nim)

    if result.returncode == 0:
        end = time.perf_counter()
        duration = end - start
        return FileResponse(
            path=output_filename,
            filename="merged_images.pdf",
            media_type="application/pdf",
            headers={"X-Duration-Seconds": str(duration)}
        )
    else:
        return {"status": "error", "error": result.stderr}

Result:

The "Dirty" Details:

• The Bridge: FastAPI handles the multi-part file uploads, saves them, and then kicks off a Nim subprocess to "plaster" the images onto an A4 page.

• The Windows Trap: If you've ever tried spawning subprocesses in asyncio on Windows, you've likely met the NotImplementedError. I bypassed this using anyio.to_thread. It's a "sync-in-async" hack that keeps the server non-blocking.

• Performance: nimpdf is impressively lightweight. It makes the "binary crunching" part of the stack feel almost instant.

Why do this? Mostly curiosity. I wanted to see how much friction there was in passing data into a systems-level binary from a high-level web framework. Turns out, once you get the subprocess logic right, it's a pretty powerful pattern.

Note: From what I've read, while the subprocess approach worked, a more "pro" move would be to compile Nim to a .so file.

Feature	Subprocess	Shared Library (.so/FFI)
Setup Complexity	Low: Just call a CLI command.	High: Requires C-bindings and type mapping.
Performance	Medium: Overhead for process startup.	Maximum: Native speed, zero startup lag.
Stability	High: If Nim crashes, Python lives.	Risky: If Nim crashes, the whole server dies.
Memory	Isolated: Separate memory space.	Shared: Very efficient but easy to leak.
Best For	Quick tools and background tasks.	High-frequency, real-time operations.

Instead of Python calling a program, Python becomes the program, executing Nim code natively via C-bindings. This removes the OS overhead of spawning processes and keeps everything in-memory.

Take a peek. Beware, it's not validated, this was just a proof of concept.

Building My First Scala DSL (and the Design Mistakes I Made)

AranaDeDoros — Tue, 20 Jan 2026 19:31:03 +0000

I’ve always liked DSLs, but building one turned out to be more humbling than I expected. ScalaCron was my first real attempt at designing an embedded DSL, and while it works, it also taught me a few lessons the hard way.

Some months I decided to pick up Scala again and make some projects. One of them was my first embedded DSL experiment : ScalaCron. A DSL to generate cronjob expressions programatically.

Just in case you aren't familiar with the term, a Domain Specific Language is a language used for very specific fields. It attempts to solve the complexity of a language by removing imperative programming in favor of a more declarative approach. It has a syntax that tells what will be done instead of how to do it. There are two types: external languages and non-external. The difference is that the former runs on top of a host language and the latter does not. Some popular DSLs of both types are: SQL, Regex, and Makefiles (external), and LINQ, Scala collections, and Gradle Kotlin DSL (non-external).

Scala syntax and abstractions make writing DSLs relatively easy.

DSL development is a two layer architecture design. I knew this before, but it hit me harder a bit too late, perhaps.

What are these two layers?
1.- Domain modeling.
2.- Syntax and interpretation layer.

Designing the domain was relatively easy, but soon enough I faced a point at which, even though I had a safe model layer, it made it difficult to make the syntax more English-like.

I had this method for expressions to validate their values:

    final def applyValidated(value: A): Either[CronError, CronExpr[A]] =
      if range.contains(value) && pf.isDefinedAt(value) && pf(value) then
        Right(At(build(value)))
      else
        Left(InvalidRange(value, range.end))

At the time it worked just fine, but when I was moving on to making the syntax prettier, I found that the handling of errors leaked through and made abstracting things harder (not impossible, but syntactically ugly).

At some point I had something like:

  import CronDSL.*

    val job = CronJobExpr.build { c =>
      c.m = * / 5
      c.h = 12.h
      c.dom = 1.dom
      c.dow = 1.dow
    }

    println(job) //*/5 12 1 1

which needed a builder and I didn't like it.

After applying some abstractions and making tradeoffs for keeping my sanity without refactor, I decided to move validation to the interpretation layer:

private def validateExpr(expr: CronExpr[Int]): List[CronError] =
      expr match {

        case At(v) =>
          validateValue(v)

        case Range(from, to) =>
          validateValue(from) ++
            validateValue(to) ++
            validateRangeOrder(from, to)

        case ListExpr(values) =>
          values.flatMap(validateValue)

        case Every(step, field) =>
          val stepErrors =
            if (step <= 0) List(InvalidStep(step)) else Nil
          stepErrors

        case Step(from, step) =>
          val stepErrors =
            if (step <= 0) List(InvalidStep(step)) else Nil
          validateValue(from) ++ stepErrors
      }

Granted it made things easier, but I still feel a bit guilty that validation was delayed this way.

In the end, I decided not to refactor as this was just an experiment and the syntax was just good enough

import domain.Models.*
import domain.Models.Minute.given
import dsl.CronDSL.{to, *}
import Days.*
import scala.language.postfixOps

object Main :
  def main(args: Array[String]): Unit =

  val job2 = cron { c =>
    c.minute(* / 5)
    c.hour(2.h)
    c.dom(1.dom)
    c.dow(Friday)
  } >> "/usr/bin/backup.sh"
  println(job2?) //same as job.schedule
  println(job2) //whole expression as string

/*
- Minute        : every 5 minutes
- Hour          : at 2
- Day of Month  : at 1
- Day of Week   : Friday
*/5 2 1 5 /usr/bin/backup.sh
*/

In an upcoming post, I’ll walk through a second DSL where I applied these lessons from the start, especially around validation, layering, and syntax design and the results were noticeably better.

ScalaCron repo