Hector Ventura

Posted on May 9

The Floci philosophy: stay tiny, feel like real AWS

#aws #opensource #architecture #testing

Fast and fake. Tiny, instant, until your code touches a real engine and the abstraction cracks.
Heavy and faithful. Closer to AWS, but a 3-second startup, hundreds of MB, a bundled Python runtime that turns every CI job into a slow morning.

I built Floci to refuse the choice. One principle:

Be the lightest thing possible. Be real where it counts.

The two halves of every AWS service

Read enough AWS API docs and you notice every service has two parts:

A control plane: "create this bucket, list my queues." Just CRUD over JSON or XML. The hard part is wire-protocol fidelity.
A data plane: "run this Lambda, connect to this database, query this Redis." This is where the real engine lives. Faking it works until it doesn't.

The control plane has no excuse to be heavy. The data plane has no excuse to be fake.

So Floci does both, on purpose, in different layers.

How it's structured

┌───────────────────────────────────────────┐
│  Floci core, Quarkus native binary               │
│  24 ms startup · 13 MiB idle                     │
│                                                  │
│  All control planes + stateless services         │
│  (S3, SQS, DynamoDB, IAM, KMS, ...)              │
└─────────────────┬─────────────────────────┘
                  │ Docker socket, on demand
                  ▼
┌───────────────────────────────────────────┐
│  Right-sized engines per service                 │
│                                                  │
│  Tiny sidecars:                                  │
│   • Athena, Firehose → floci-duck (DuckDB).     │
│                                                  │
│  Heavy real engines:                             │
│   • Lambda → real container                     │
│   • RDS    → real Postgres / MySQL              │
│   • Cache  → real Redis / Valkey                │
│   • MSK    → real Kafka                         │
└───────────────────────────────────────────┘

One tiny core. Real engines pulled in only when you actually use the service that needs them.

Three patterns, not two

The interesting part of the design is that there are three patterns, not the usual two. Each picks the smallest thing that gives you real behavior:

1. Stateless / metadata → in-process.
S3, SQS, DynamoDB, IAM. There's no engine to fake, just specs to implement correctly. Floci does it in 13 MiB.

2. Small embedded engine exists → tiny sidecar.
Athena doesn't need a Presto cluster. It needs correct SQL execution over data in S3. So Floci uses floci-duck, a small Rust binary wrapping DuckDB. Real columnar SQL, no JVM, no Hive metastore. The same sidecar powers Firehose's Parquet conversion. That's the philosophy at its purest: pick the lightest real engine.

3. No embeddable substitute → real heavy engine.
RDS, ElastiCache, MSK, OpenSearch, Lambda. Your code speaks PostgreSQL or RESP or Kafka or runs as actual containers, there's no faking it. Floci spins up the real thing on demand and gets out of the way.

The rule across all three: never reimplement an engine that already exists. Glue the AWS API onto it, then disappear.

What this buys you

Lightweight isn't marketing. A 24ms cold start means you spin Floci up per-test without thinking. ~13 MiB at idle fits free-tier CI runners. ~90 MB image is auditable. docker compose up finishes before you've alt-tabbed.

Fidelity isn't a checkbox. Lambda runs in real Lambda runtime images. RDS speaks real PostgreSQL. ElastiCache speaks real RESP. Athena runs real SQL through DuckDB against your real S3 data. If your test passes, your code actually works.

The tradeoffs I accept

Floci needs the Docker socket for engine-backed services. Fair deal.
Some services start slower than the core. Postgres takes a few seconds to boot. Floci itself is 24ms, but CreateDBInstance takes as long as Postgres takes. No way around that without lying.

These are the price of not lying to you.

Why it matters

Every emulator decision comes down to: do you want your tests to tell you the truth?

A bloated emulator gets skipped. A fast-but-fake one passes tests that fail in production. Floci's whole architecture is built to dodge both ends, pick the smallest real thing for every service, and never the bloated thing that pretends.

That's it. The rest is just code.

docker run --rm -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  floci/floci:latest

🔗 github.com/floci-io/floci
📚 floci.io/floci
💬 floci.slack.com

If you've ever shipped a bug because a test mock lied to you. I'd love to know which service did it. That's what Floci's roadmap is built from.

DEV Community