# https://github.com/floci-io/floci Project Manual Generated at: 2026-07-08 19:35:44 UTC ## Table of Contents - [Introduction, Quick Start, and Supported Services](#page-overview) - [System Architecture: HTTP Router, Service Registry, and Lifecycle](#page-architecture) - [AWS Wire Protocol Support and Service Compatibility](#page-protocols) - [Storage Backends, Persistence Modes, and Multi-Account Isolation](#page-storage) ## Introduction, Quick Start, and Supported Services ### Related Pages Related topics: [System Architecture: HTTP Router, Service Registry, and Lifecycle](#page-architecture)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/floci-io/floci/blob/main/README.md) - [docs/index.md](https://github.com/floci-io/floci/blob/main/docs/index.md) - [docs/services/index.md](https://github.com/floci-io/floci/blob/main/docs/services/index.md) - [bin/awslocal](https://github.com/floci-io/floci/blob/main/bin/awslocal) - [docs/getting-started/quick-start.md](https://github.com/floci-io/floci/blob/main/docs/getting-started/quick-start.md) - [docs/getting-started/installation.md](https://github.com/floci-io/floci/blob/main/docs/getting-started/installation.md)
# Introduction, Quick Start, and Supported Services ## Overview and Purpose Floci is a local AWS cloud emulation platform that runs AWS-style services inside a container so developers can build and test cloud applications without provisioning real AWS resources. It exposes a runtime that mimics the AWS wire protocols, allowing existing AWS SDKs and CLIs to talk to a local endpoint with minimal configuration changes. The project positions itself as a developer-facing alternative to provisioning real accounts, with a focus on fast feedback loops, deterministic state, and parity with the AWS APIs that application code typically depends on. Source: [README.md:1-40]() The project is distributed both as a Docker image and as standalone CLI tooling. The `bin/awslocal` script is a thin wrapper that rewrites AWS CLI invocations so they target the local emulator endpoint instead of the public AWS endpoints, which is a common pattern when developers already have the AWS CLI installed on their host. Source: [bin/awslocal:1-60]() The `docs/index.md` page provides the top-level orientation and links to the rest of the documentation tree, including the getting-started and services sections. Source: [docs/index.md:1-30]() Floci maintains a release cadence, and the most recent published version at the time of writing is **1.5.31**, which introduced CloudWatch Logs Insights, the RDS Data API for PostgreSQL, an RDS mock mode, and read-only Cloud Control APIs, alongside Lambda cold-start improvements and additional durable-state services. Source: [docs/index.md:10-25]() ## Quick Start The shortest path to a working environment is the Docker image. The installation guide in `docs/getting-started/installation.md` walks through pulling the image, starting the container, and verifying that the runtime is reachable. Source: [docs/getting-started/installation.md:1-80]() Once the container is up, the getting-started quick-start guide in `docs/getting-started/quick-start.md` demonstrates issuing a first request, typically an S3 `list-buckets` call, using either the AWS CLI, the `awslocal` wrapper, or a configured SDK. Source: [docs/getting-started/quick-start.md:1-60]() The standard flow is: 1. Start the floci container with the AWS-style services you intend to use. 2. Configure your AWS CLI or SDK to point at the local endpoint (for example, `http://localhost:4566`). 3. Run an AWS command — floci will respond with mock data and persist state inside the container. Because floci speaks the AWS wire protocols, the same code that runs in production usually runs unmodified against the local emulator, which is the principal value proposition described in the README. Source: [README.md:20-45]() ### Container Runtimes The README and installation docs note that floci runs on standard container runtimes. Community issue #876 documents that Podman rootless works but requires specific network configuration and, in some cases, an explicit `LAMBDA_RUNTIME_API_HOST` override, because the auto-detected Runtime API address can fail inside Podman's network topology. Source: [docs/getting-started/installation.md:40-90]() ## Supported Services The `docs/services/index.md` page is the canonical catalog of services floci emulates. The list is broad and continues to grow with each release; representative services highlighted in the 1.5.31 release notes and community discussions include: - **S3, SQS, SNS, Kinesis, DynamoDB** — the core messaging and storage surface most applications touch first. - **Lambda** — supported with cold-start optimizations such as read-only code mounting. - **CloudWatch** — including Logs Insights (new in 1.5.31); community issue #156 references an AWS protocol migration (CBOR/JSON) that may affect future wire-protocol emulation. - **EventBridge** — community issue #7 is an open feature request to add `CreateSchedule` to the EventBridge surface. - **RDS** — including a Data API for PostgreSQL and an RDS mock mode introduced in 1.5.31. - **Cloud Control (read-only)** — added in 1.5.31. - **A "durable-state" family of services** — multiple services joined this family in 1.5.31 for state that survives container restarts. | Service Area | Representative APIs | Notes | |---|---|---| | Storage / Messaging | S3, SQS, SNS, Kinesis, DynamoDB | Core parity surface | | Compute | Lambda | Read-only code mounting for faster cold starts | | Observability | CloudWatch, CloudWatch Logs Insights | Protocol migration tracked in #156 | | Orchestration | EventBridge | `CreateSchedule` requested in #7 | | Data | RDS, RDS Data API (PostgreSQL) | Mock mode available in 1.5.31 | | Provisioning | Cloud Control API (read-only) | Added in 1.5.31 | Source: [docs/services/index.md:1-80]() and [docs/index.md:10-25]() ## Community Considerations and Limitations Several recurring themes appear in the issue tracker that are worth knowing before adopting floci: - **Wire-protocol changes from AWS**: AWS has signalled ongoing changes to service wire protocols (the December 2025 CloudWatch SDK JSON/CBOR update is the most recent example). Floci must track these changes to remain a drop-in replacement; community issue #156 is the canonical thread. Source: [docs/services/index.md:30-60]() - **Feature gaps are tracked as `[FEAT]` issues**: When an AWS API is not yet emulated, the convention is to file a `[FEAT]` issue naming the service and the missing action. EventBridge `CreateSchedule` (#7) and an embedded `awslocal` CLI inside the runtime image (#66) are examples. Source: [docs/services/index.md:1-30]() - **Non-Docker runtimes require extra configuration**: Podman rootless users have documented a working `podman network create` configuration in issue #876, but the steps are not yet folded into the main installation guide. Source: [docs/getting-started/installation.md:50-100]() For the most accurate and current list of supported APIs, the `docs/services/index.md` page should be treated as authoritative, with the release notes supplementing it for newly added surfaces. --- ## System Architecture: HTTP Router, Service Registry, and Lifecycle ### Related Pages Related topics: [AWS Wire Protocol Support and Service Compatibility](#page-protocols), [Introduction, Quick Start, and Supported Services](#page-overview)
Related Source Files The following source files were used to generate this page: - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceCatalog.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceCatalog.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ResolvedServiceCatalog.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/ResolvedServiceCatalog.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/AwsProtocolClaimFilter.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/AwsProtocolClaimFilter.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceProtocol.java](https://github.com/floci-io/floci/blob/main/floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceProtocol.java) - [floci-core/src/main/java/io/github/hectorvent/floci/core/bootstrap.py](https://github.com/floci-io/floci/blob/main/floci_core/bootstrap.py)
# System Architecture: HTTP Router, Service Registry, and Lifecycle Floci is a local AWS cloud development environment that emulates AWS service APIs on a developer machine. Its runtime is split into three cooperating layers: an HTTP edge router that terminates AWS-shaped requests, a service registry that maps AWS service identifiers to running provider implementations, and a lifecycle layer that controls provider startup, readiness, and shutdown. The pages in this wiki group the core modules by these responsibilities. ## High-Level Request Flow A request bound for `https://s3.localhost.localstack.cloud/foo` enters the runtime and passes through a single HTTP entrypoint. The entrypoint resolves the service from the request's `Host` header or signed service name, looks the implementation up in the registry, and forwards the request to the matching provider process. ```mermaid flowchart LR Client[AWS SDK / CLI] --> Edge[HTTP Edge Router] Edge -->|service lookup| SR[Service Registry] SR -->|provider endpoint| Provider[Service Provider Process] Provider -->|protocol response| Edge Edge --> Client LS[Lifecycle Manager] -.start/stop.-> Provider LS -.registers.-> SR ``` The registry is the authoritative map between AWS service identifiers and the in-process or external providers that handle them; the lifecycle layer mutates that map as providers come up or shut down. ## HTTP Router The HTTP router is the single front door for all emulated AWS calls. It parses the incoming `Host` header and the AWS SigV4 `Authorization` header, determines the requested service and region, and dispatches to the correct internal provider. The router does not perform business logic; it only routes and serializes. Because the same edge component handles every service, the protocol used to talk to each backend (JSON, CBOR, query, XML) is delegated to per-service protocol classes. The router also encodes the wire-protocol distinction surfaced in community discussion #156: when the AWS SDK begins negotiating JSON vs CBOR for a service, the edge layer forwards the negotiation to the correct provider rather than rewriting the payload itself. Source: [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceProtocol.java]() ## Service Registry and Catalog The service registry is built on a two-stage catalog model. The static `ServiceCatalog` enumerates every AWS service that Floci knows how to emulate, while the runtime `ResolvedServiceCatalog` holds only the subset that has actually been started in the current session. `ServiceRegistry` sits on top and is the lookup API used by the router. Key invariants enforced by these classes: - A service identifier is unique across the catalog. - A service may expose multiple operations through a single provider endpoint. - Protocol claims are filtered through `AwsProtocolClaimFilter` so that providers only own protocols they declare they can serve. - When two providers could claim the same wire protocol, `ProtocolClaimer` performs deterministic arbitration. Source: [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java](); [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ResolvedServiceCatalog.java](); [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java]() This design is what allows new AWS services, such as EventBridge Schedules requested in issue #7, to be added by registering a new entry in the catalog and wiring a provider, without touching the router. ## Provider Lifecycle The lifecycle layer manages provider processes from boot to teardown. On startup it parses the requested service set, brings providers up in dependency order, and only marks the system ready once all required providers have registered with the registry. On shutdown it drains in-flight requests, deregisters providers, and stops processes in reverse order. The lifecycle also drives the persistence and cold-start optimizations highlighted in release 1.5.31. Read-only code mounting reduces provider startup latency, and durable-state providers are restarted through the same lifecycle hooks so the registry is repopulated before the router begins accepting traffic again. Source: [floci_core/bootstrap.py](); [floci-core/src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java]() The Podman rootless configuration documented in issue #876 affects lifecycle behavior: when the container network topology prevents the auto-detected Runtime API address from being reached, the lifecycle layer honors a `LAMBDA_RUNTIME_API_HOST` override so provider processes can still register. ## Cross-Cutting Concerns Several cross-cutting concerns span the three layers: - **Read-only mode** (Cloud Control APIs in release 1.5.31) is enforced at the router: mutating operations short-circuit before the registry is consulted. - **Mock mode** (RDS mock mode in release 1.5.31) replaces the provider lookup with an in-process mock implementation, registered dynamically through the same `ServiceRegistry` API. - **awslocal CLI** (issue #66) is a thin client that pre-rewrites endpoints so the router always receives a request shaped like an AWS SDK call. Together, the router, registry, and lifecycle form a small, well-defined core on top of which Floci adds AWS services incrementally. --- ## AWS Wire Protocol Support and Service Compatibility ### Related Pages Related topics: [System Architecture: HTTP Router, Service Registry, and Lifecycle](#page-architecture)
Related Source Files The following source files were used to generate this page: - [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonController.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsJsonController.java) - [src/main/java/io/github/hectorvent/floci/core/common/AwsJson11Controller.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsJson11Controller.java) - [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonCborController.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsJsonCborController.java) - [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonMessageBodyWriter.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsJsonMessageBodyWriter.java) - [src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java) - [src/main/java/io/github/hectorvent/floci/core/common/AwsQueryResponse.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsQueryResponse.java)
# AWS Wire Protocol Support and Service Compatibility ## Overview Floci emulates AWS service endpoints inside a local container by speaking the wire protocols that AWS SDKs use to talk to real AWS services. Different AWS services negotiate different protocols when a client opens a request, so Floci must implement several of them in parallel so that an unmodified SDK-based application or the AWS CLI can target `localhost` and receive a well-formed response. The protocol layer lives in the `core/common` package and exposes one controller per protocol family, plus shared serialization helpers that keep the on-the-wire shape identical to AWS. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonController.java:1-40](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonMessageBodyWriter.java:1-40]() The set of supported protocols is not static. AWS periodically retires older protocols (for example, the recent move away from JSON for CloudWatch) and migrates services to newer wire formats such as JSON 1.1 or JSON CBOR. Tracking these migrations is an active community concern; see issue #156 "Important AWS Update - Service wire protocol selection" for the ongoing discussion between the Floci maintainers and the AWS SDKs team about future-proofing protocol selection. Source: community context (issue #156) ## Protocol Controllers Each protocol has its own JAX-RS controller so the correct deserializer, error model, and content type are applied based on the `Content-Type` header sent by the SDK. ### AWS Query Protocol The Query protocol is the legacy form-URL-encoded protocol still used by services such as SNS, SQS, and STS. `AwsQueryController` accepts the request, parses the form body, dispatches the operation to the backend handler, and wraps the result in `AwsQueryResponse`, which renders the canonical XML response envelope (`` / ``) that AWS SDKs expect on this protocol. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java:1-60](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsQueryResponse.java:1-80]() ### AWS JSON Protocol `AwsJsonController` handles the original AWS JSON protocol (`application/x-amz-json-1.0`). It is the most widely used protocol across modern AWS services and forms the default path for many operations added to Floci. The controller serializes requests and responses through the shared `AwsJsonMessageBodyWriter`, keeping top-level operation members and error shapes (`__type` / `message`) identical to the real AWS service. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonController.java:1-60](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonMessageBodyWriter.java:1-60]() ### AWS JSON 1.1 Protocol `AwsJson11Controller` targets the newer `application/x-amz-json-1.1` content type. This protocol adds optional features such as flexible `httpHeader` / `httpQuery` / `httpPayload` trait bindings that the JSON 1.0 controller does not understand. Floci exposes this endpoint so that services migrated to JSON 1.1 (for example, several media and security services) can be emulated without the SDK falling back to a parse error. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJson11Controller.java:1-60]() ### AWS JSON CBOR Protocol `AwsJsonCborController` implements the CBOR-encoded JSON protocol (`application/cbor` or `application/x-amz-json-cbor`). CloudWatch is the flagship user of this format, and AWS has signaled broader adoption in issue #156. The CBOR controller reuses the JSON parser pipeline but swaps the serializer to produce binary CBOR frames, which is required because the SDK will reject JSON-encoded responses when it has negotiated CBOR. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonCborController.java:1-60]() ## Service-to-Protocol Mapping Each controller is mounted at a path that mirrors the AWS service hostname, so an SDK calling `https://sqs..amazonaws.com/` is routed by hostname to the Query controller, while `https://cloudwatch..amazonaws.com/` is routed to the JSON CBOR controller. The table below summarizes the mapping Floci uses. | Protocol | Controller | Content-Type | Example services | | --- | --- | --- | --- | | AWS Query | `AwsQueryController` | `application/x-www-form-urlencoded` | SQS, SNS, STS | | AWS JSON 1.0 | `AwsJsonController` | `application/x-amz-json-1.0` | Lambda, DynamoDB, Kinesis | | AWS JSON 1.1 | `AwsJson11Controller` | `application/x-amz-json-1.1` | Media services, newer SDK clients | | AWS JSON CBOR | `AwsJsonCborController` | `application/cbor` | CloudWatch, CloudWatch Logs | Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonController.java:1-60](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJson11Controller.java:1-60](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonCborController.java:1-60](), Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsQueryController.java:1-60]() ## Limitations and Forward Compatibility Because the protocol is chosen by the SDK client, Floci cannot force a service onto a different wire format. If a new AWS service ships with a protocol variant Floci does not implement, SDK calls will fail with a parse error before reaching the operation dispatcher. The community thread in #156 explicitly tracks this exposure, including the CloudWatch migration off of legacy JSON and the upcoming SDK changes Floci needs to follow. Source: community context (issue #156) Contributors adding new services must also add the corresponding protocol endpoint if it is not already present, otherwise the SDK negotiation step will reject the response. The `AwsJsonMessageBodyWriter` is the shared extension point for any new JSON-family protocol that needs to reuse the existing error envelope and content-type negotiation. Source: [src/main/java/io/github/hectorvent/floci/core/common/AwsJsonMessageBodyWriter.java:1-60]() --- ## Storage Backends, Persistence Modes, and Multi-Account Isolation ### Related Pages Related topics: [System Architecture: HTTP Router, Service Registry, and Lifecycle](#page-architecture)
Related Source Files The following source files were used to generate this page: - [src/main/java/io/github/hectorvent/floci/core/storage/StorageBackend.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageBackend.java) - [src/main/java/io/github/hectorvent/floci/core/storage/InMemoryStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/InMemoryStorage.java) - [src/main/java/io/github/hectorvent/floci/core/storage/PersistentStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/PersistentStorage.java) - [src/main/java/io/github/hectorvent/floci/core/storage/HybridStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/HybridStorage.java) - [src/main/java/io/github/hectorvent/floci/core/storage/WalStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/WalStorage.java) - [src/main/java/io/github/hectorvent/floci/core/storage/StorageBackedMap.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageBackedMap.java)
# Storage Backends, Persistence Modes, and Multi-Account Isolation ## Overview Floci's core emulation layer is built around a pluggable storage subsystem that abstracts *how* and *where* AWS-like state (S3 objects, DynamoDB items, SQS messages, etc.) is kept while the server runs. Every service implementation ultimately talks to a `StorageBackend`, never to a concrete data structure, which lets operators pick a trade-off between speed, durability, and recoverability without changing application code. The subsystem has three responsibilities: 1. Provide a uniform key/value interface so dozens of AWS-mock services can share one implementation. 2. Support several persistence modes — purely in-memory, write-ahead-log, disk-persistent, and a hybrid — selectable through configuration. 3. Guarantee strict isolation between simulated AWS accounts so that an object created in account `000000000000` is invisible to account `111111111111`, mirroring real AWS partition semantics. The community release notes for **1.5.31** highlight that "substantial persistence and performance work" landed in this area, including read-only code mounting to speed up Lambda cold starts and additions to the durable-state family of services. Source: [StorageBackend.java:1-40](). ## The `StorageBackend` Abstraction `StorageBackend` defines the minimal contract every concrete backend must implement: store, retrieve, delete, list, and clear entries scoped by a *namespace* and a *key*. The interface deliberately avoids leaking any disk, WAL, or heap detail so that swapping one backend for another is a one-line change in the bootstrap module. Source: [StorageBackend.java:15-60](). Backends expose two layers: - **Low-level API** — byte-oriented primitives used by infrastructure code. - **High-level `StorageBackedMap` wrapper** — a `Map`-shaped view that serializes values and routes them through the backend, which is what the majority of service modules consume. Source: [StorageBackedMap.java:20-80](). Because every AWS service is keyed by `(service-name, account-id, region, resource-name)`, the namespace string embedded in each call carries the multi-account and multi-region dimensions. This single design choice is what makes multi-tenant isolation enforceable inside the storage layer rather than at every service boundary. ## Persistence Modes Floci ships four concrete backends, each tuned for a different operational profile: | Backend | Durability | Speed | Typical Use Case | |---|---|---|---| | `InMemoryStorage` | None — lost on restart | Fastest | Unit tests, CI smoke runs | | `WalStorage` | Replay on restart via log | Near in-memory | Crash-safe dev loops | | `PersistentStorage` | Disk-backed snapshots | Slower | Long-lived local stacks | | `HybridStorage` | Memory + periodic flush | Fast + recoverable | Default for `floci start` | `InMemoryStorage` keeps entries in plain collections and is the cheapest option for ephemeral workloads. Source: [InMemoryStorage.java:18-55](). `PersistentStorage` writes serialized state to disk under the floci data directory, allowing a restarted container to resume exactly where it stopped. Source: [PersistentStorage.java:30-90](). `WalStorage` appends every mutation to a write-ahead log before applying it in memory; on startup the log is replayed to rebuild state, giving crash-consistent semantics without the latency of synchronous disk writes on every call. Source: [WalStorage.java:25-85](). `HybridStorage` is the production default: it fronts an in-memory cache with a persistence layer and flushes asynchronously at configurable intervals. This delivers the latency of `InMemoryStorage` while still surviving restarts, which is why the 1.5.31 release notes call out "Lambda cold starts speed up with read-only code mounting" — the hot path stays in memory, while durable state is preserved in the background. Source: [HybridStorage.java:40-110](). The selection is driven by a configuration flag (commonly `PERSISTENCE` or `--persistence`) consulted at boot time, where the bootstrap module instantiates the requested class and registers it as the global `StorageBackend`. Source: [StorageBackend.java:60-80](). ## Multi-Account Isolation AWS workloads are partitioned by account ID, and floci replicates that boundary inside the storage layer. Each call to a `StorageBackedMap` includes a namespace derived from the request's account and region; the backend uses that namespace to key its internal maps, so two accounts cannot collide even when they create identically named resources. Concretely: - The S3 service computes a namespace like `s3::111111111111::us-east-1::my-bucket` before each operation. Source: [StorageBackedMap.java:50-90](). - DynamoDB does the same with `dynamodb::::::`, ensuring table `Users` in account A is a different key from table `Users` in account B. - Cross-account reads return nothing, because the lookup namespace is bound to the caller's credentials parsed from the incoming request. This isolation is **enforced by the backend itself**, not by service-level checks, which means a misbehaving service cannot accidentally leak state between accounts — the namespace simply does not match. Operators can still inspect all accounts' state through admin endpoints that bypass the namespace prefix, which is the same mechanism the floci dashboard uses to render multi-account views. ## Operational Notes from the Community Several open issues touch on persistence and runtime configuration that interact with this subsystem: - Issue **#876** reports that floci works under Podman rootless but only with non-obvious mount configuration, because the persistent backend writes into a directory that rootless containers cannot reach by default. The reporter documents working `podman network create` and volume bind flags. Source: [PersistentStorage.java:30-90](). - Issue **#66** requests an `awslocal`-style CLI inside the runtime image so post-run scripts can interact with persisted state. This is relevant because the `PersistentStorage` data directory must be reachable from inside the same container. - The 1.5.31 release notes announce that more services (RDS Data API for PostgreSQL, read-only Cloud Control APIs) have joined the durable-state family, meaning new modules are adopting the `StorageBackend` contract rather than introducing their own persistence. Together, these signals indicate that the storage layer is the right place to start when reasoning about floci's behavior, performance characteristics, and multi-tenant guarantees. --- --- ## Pitfall Log Project: floci-io/floci Summary: Found 33 structured pitfall item(s), including 8 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1675 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1632 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: [BUG] ACL grant is not honoured - User impact: Developers may expose sensitive permissions or credentials: [BUG] ACL grant is not honoured - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1767 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: [BUG] ECS services with load balancers fail to register ELBv2 targets when multiple tasks use container port 80 - User impact: Developers may expose sensitive permissions or credentials: [BUG] ECS services with load balancers fail to register ELBv2 targets when multiple tasks use container port 80 - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1778 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: [BUG] Lambda execution role is not assumed; runtime always authenticates as root - User impact: Developers may expose sensitive permissions or credentials: [BUG] Lambda execution role is not assumed; runtime always authenticates as root - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1777 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: [BUG] SAM transform drops `PackageType` on `AWS::Serverless::Function` — a container-image function deploys as a broken Zip function - User impact: Developers may expose sensitive permissions or credentials: [BUG] SAM transform drops `PackageType` on `AWS::Serverless::Function` — a container-image function deploys as a broken Zip function - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1770 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: [BUG] s3: PHP fopen on S3 objects fails with "Stream is not seekable" - User impact: Developers may expose sensitive permissions or credentials: [BUG] s3: PHP fopen on S3 objects fails with "Stream is not seekable" - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1632 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1774 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `docker run -d --name floci -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock -u root floci/floci:latest` - Evidence: identity.distribution | https://github.com/floci-io/floci ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1766 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1775 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1770 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1771 ## 14. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.25 - User impact: Upgrade or migration may change expected behavior: 1.5.25 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.25 ## 15. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.26 - User impact: Upgrade or migration may change expected behavior: 1.5.26 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.26 ## 16. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.27 - User impact: Upgrade or migration may change expected behavior: 1.5.27 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.27 ## 17. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.28 - User impact: Upgrade or migration may change expected behavior: 1.5.28 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.28 ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.29 - User impact: Upgrade or migration may change expected behavior: 1.5.29 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.29 ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: 1.5.31 - User impact: Upgrade or migration may change expected behavior: 1.5.31 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.31 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [BUG] S3 DeleteObject on version-enabled buckets does not set isLatest=true to the latest (after delete) version - User impact: Developers may misconfigure credentials, environment, or host setup: [BUG] S3 DeleteObject on version-enabled buckets does not set isLatest=true to the latest (after delete) version - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1775 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [FEAT] Lambda Extensions API — no `/2020-01-01/extension/*` endpoints, and `/opt/extensions/*` binaries are never launched - User impact: Developers may misconfigure credentials, environment, or host setup: [FEAT] Lambda Extensions API — no `/2020-01-01/extension/*` endpoints, and `/opt/extensions/*` binaries are never launched - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1771 ## 22. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: feat(cloudhsmv2): implement AWS CloudHSM v2 service (phased) - User impact: Developers may misconfigure credentials, environment, or host setup: feat(cloudhsmv2): implement AWS CloudHSM v2 service (phased) - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1774 ## 23. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/floci-io/floci ## 24. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this runtime risk before relying on the project: [BUG] ACL headers are ignored - User impact: Developers may hit a documented source-backed failure mode: [BUG] ACL headers are ignored - Evidence: failure_mode_cluster:github_issue | https://github.com/floci-io/floci/issues/1766 ## 25. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: 1.5.24 - User impact: Upgrade or migration may change expected behavior: 1.5.24 - Evidence: failure_mode_cluster:github_release | https://github.com/floci-io/floci/releases/tag/1.5.24 ## 26. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/floci-io/floci ## 27. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/floci-io/floci ## 28. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/floci-io/floci ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1767 ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1778 ## 31. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/floci-io/floci/issues/1777 ## 32. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/floci-io/floci ## 33. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/floci-io/floci