The Problem

Developers need a locally runnable AWS‑compatible stack that starts instantly, consumes minimal resources, and does not require authentication tokens. Existing community editions are becoming gated or oversized, forcing teams to provision cloud accounts just for integration tests.

What This Does

floci delivers a lightweight emulator that mimics over 30 AWS services. The core runtime lives in src/ (511 files, mainly Java) and is packaged as a Docker image via the root Dockerfile. Compatibility suites in compatibility-tests/ validate behavior across languages—Node (sdk-test-node), Python (sdk-test-python), Go (sdk-test-go), Java (sdk-test-java) and Rust (sdk-test-rust). The README advertises a one‑liner launch:

docker compose up

which pulls the pre‑built image (hectorvent/floci) and starts the HTTP router on port 4566.

How It Is Wired

Execution starts in the root Dockerfile → Dockerfile.native (or Dockerfile.jvm-package for the JVM build). The image runs the Java main class defined in src/main/java/com/floci/App.java (the exact class name is inferred from the Maven build). This class instantiates the Vert.x HTTP router (Router in src/main/java/com/floci/router/Router.java) which dispatches incoming AWS SDK calls to service handlers (e.g., src/main/java/com/floci/service/s3/S3Service.java).

The measured import graph contains 48 internal modules with 23 import edges and no circular dependencies. The most connected node is the test harness compatibility-tests/sdk-test-node/tests/setup.ts (22 inbound imports, 0 outbound). It loads shared fixtures for the Node SDK tests and therefore represents the largest blast radius—any change here can affect all Node compatibility tests.

Deeply nested control flow appears in several test files (sdk-test-go/tests/s3_notifications_test.go, sdk-test-java/src/main/java/com/floci/test/TestFixtures.java, sdk-test-java/src/test/java/com/floci/test/ApiGatewayV2ExecuteTest.java) where indentation reaches nine levels, increasing cognitive load. No hub or cycle exists in the production code; the only hub is the test setup module.

External effects: the runtime reads static certificates from src/main/resources/certs/amazon-root-ca.pem (marked as a potential secret‑shaped path) and writes no persistent data; all state is in‑memory. Compatibility tests spin up auxiliary containers (see compatibility-tests/compat-cdk/Dockerfile and language‑specific Dockerfiles) that invoke the emulator via its public endpoint.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/floci
cd floci

# Build the Docker image (optional – pre‑built image available)
docker build -f Dockerfile -t floci:local .

# Start the emulator (docker‑compose file is in the repo root)
docker compose up -d

The emulator listens on http://localhost:4566. SDKs can be pointed at this endpoint by setting the usual AWS environment variables, e.g., AWS_ENDPOINT_URL=http://localhost:4566. No additional configuration files are required; the default certificate in src/main/resources/certs/amazon-root-ca.pem is bundled.

Real‑World Use

A CI pipeline can replace external AWS calls with floci by adding the above docker compose up step before integration tests. For example, a Maven verify phase can depend on the container, letting Java integration tests (compatibility-tests/sdk-test-java/...) run against the local emulator without network latency or credential management.

Code Health & Issues

  • High (108) – Deep nesting (59 occurrences) in test code makes maintenance difficult.
  • Medium (148) – Hub module compatibility-tests/sdk-test-node/tests/setup.ts is a single point of change for many tests.
  • Low (0) – No low‑severity findings reported.
  • Security – Secret‑shaped path src/main/resources/certs/amazon-root-ca.pem flagged; review if it contains private material.
  • Repo hygiene – CI defined in .github/workflows/; Dockerfile present; LICENSE (MIT) present; lockfiles exist; however, committed secrets were detected.

The Bottom Line

floci offers a genuinely free, fast‑starting AWS emulator with a modest Docker footprint (~90 MB) and broad service coverage, suitable for local development and CI pipelines. The production codebase is well‑structured with no circular dependencies, but the test harness contains high‑impact hubs and deep nesting that will require refactoring for long‑term stability. Teams that need rapid, token‑free AWS emulation will find it valuable; contributors should prioritize cleaning up the test scaffolding.