FlociClone/CONTRIBUTING.md

Contributing to Floci

Thank you for your interest in contributing! Floci is a community-driven project and all contributions are welcome.

Join us on Slack: it is the fastest way to reach maintainers. Ask about AWS behaviour, sanity-check an approach before you build it, or get unstuck on a PR.

Ways to Contribute

• Bug reports: open an issue with a minimal reproduction
• Feature requests: open an issue describing the AWS behavior you need
• Pull requests: bug fixes, new service implementations, or improvements
• Compatibility tests: add cases to ./compatibility-tests/

Getting Started

Prerequisites

• Java 25+
• Maven 3.9+
• Docker (for integration tests that spin up Lambda/RDS/ElastiCache)

Any Java 25+ distribution will work. If you need to install it, SDKMAN is a convenient option:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 25-open

Build & Run

This project includes a Maven wrapper, so you don't need to install Maven separately:

git clone https://github.com/floci-io/floci.git
cd floci
./mvnw quarkus:dev     # hot reload on port 4566

If you prefer to use your own Maven installation (3.9+), you can use mvn instead of ./mvnw.

Run Tests

./mvnw test                                          # all tests
./mvnw test -Dtest=SsmIntegrationTest                # single class
./mvnw test -Dtest=SsmIntegrationTest#putParameter   # single method

Branching Model

Floci uses a tag-driven release model. Merging a PR never publishes a release image. main is published once a day as the nightly channel, and a stable release is published only when a maintainer runs the "Release Cut" workflow (.github/workflows/release-cut.yml, workflow_dispatch). That workflow runs semantic-release, which bumps pom.xml, writes CHANGELOG.md, commits, and pushes the X.Y.Z tag. The tag then triggers .github/workflows/release.yml, which builds and publishes the release images to Docker Hub and public ECR.

Branch / tag	Purpose	Docker published?
main	Integration branch: all PRs merge here. Treated as unstable.	Nightly only (nightly, nightly-<date>, nightly-compat, nightly-<date>-compat) via nightly.yml
X.Y.Z tag	Signals a production release. Pushed by the Release Cut workflow.	Yes (x.y.z, latest, x.y.z-compat, latest-compat) via release.yml

Commit Message Format

This project uses Conventional Commits: semantic-release reads these to generate the changelog and version bumps automatically.

The PR title is validated automatically by CI and must follow this format, since it becomes the squash-merge commit message that semantic-release reads.

Format

<type>[optional scope]: <description>

• type: one of the values in the table below (lowercase)
• scope: optional, in parentheses, identifies the service or area (e.g. s3, dynamodb, core)
• description: short summary in the imperative mood, no trailing period
• Append ! before the colon to signal a breaking change: feat(api)!:

Type	When to use	Version bump
feat	New AWS API action or service	minor
fix	Bug fix or AWS compatibility correction	patch
perf	Performance improvement	patch
revert	Reverts a previous commit	patch
docs	Documentation only	none
style	Formatting, whitespace, no logic change	none
chore	Build, CI, dependencies, housekeeping	none
refactor	Code restructure without behavior change	none
test	Adding or updating tests	none
build	Build system or tooling changes	none
ci	CI workflow changes	none
BREAKING CHANGE	Footer or ! suffix, incompatible change	major

Valid examples ✅

feat(dynamodb): add PartiQL ExecuteStatement support
fix(s3): make us-east-1 bucket creation idempotent
perf(kinesis): reduce lock contention in shard iterator
chore: release 1.5.16
docs: update README with new configuration options
refactor(sqs): extract message visibility logic
test(kms): add encrypt/decrypt round-trip test
feat!: remove legacy v1 endpoint
fix(dynamodb)!: correct TransactWriteItems error shape
ci: add conventional commits lint workflow
build: bump Quarkus to 3.32.3

Invalid examples ❌

Add PartiQL support                  # missing type
Feature: add something               # "Feature" is not a valid type
feat : space before colon            # space before colon
feat(dynamodb)add missing colon      # missing colon
FIX(s3): uppercase type              # type must be lowercase
feat(my scope): scope has spaces     # scope cannot contain spaces
fix(): empty scope                   # empty scope
feat(s3):no space after colon        # missing space after colon
wip: still working on this          # "wip" is not a recognised type

Do not include Co-Authored-By trailers for AI tools in commit messages. Attribution should be limited to human contributors.

CI enforces this: the Commits omit AI attribution trailers check fails a pull request whose commits carry a Co-Authored-By for an identity that is not a person (one whose GitHub address belongs to a bot account, or that uses a noreply@ mailbox), along with the session and generator lines such tools add on their own. It never judges a co-author by name, so co-authoring a person is always fine; that trailer is how GitHub credits reviewers on a squash merge. dependabot[bot] is allowlisted. If the check fires, drop the offending lines with git commit --amend (or a rebase for several commits) and force-push.

Architecture

See AGENTS.md for a detailed description of the three-layer architecture (Controller → Service → Storage), the AWS wire protocol mapping, and conventions for adding new services.

AGENTS.md is the canonical agent instructions file for this repository, following the AGENTS.md standard. If your coding agent expects a different filename, create a local symlink to AGENTS.md instead of copying the file.

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
ln -s AGENTS.md COPILOT.md

Code Style

AGENTS.md carries the full list. The rules worth knowing before your first PR:

• Write explicit types. Do not use var. Floci reproduces AWS wire contracts, so the concrete type at a call site is usually what a reviewer needs to see: whether a value is a LinkedHashMap or a Map, an AWS model type or a JDK one. The one exception is a record deconstruction pattern.
• Import the classes you use. No fully-qualified names inline. new ArrayList<>(), never new java.util.ArrayList<>(). Qualify inline only for a genuine name collision in that file, and say in a comment what collides.
• No wildcard imports in src/main. Static wildcards are fine in tests.
• Never leave a catch block empty. If swallowing is correct, name the variable ignored or expected and say why in a comment.
• Always use braces in conditionals, and use constructor injection.
• Tests: JUnit 5 with Hamcrest and RestAssured. Name methods as a camelCase sentence or method_scenario_expectation, never testX.

Existing code does not yet satisfy all of these everywhere. Match the rules in code you add or change; leave unrelated cleanups for their own PR.

Adding a New AWS Service

1. Create a package under src/main/java/.../services/<service>/
2. Add a Controller (follow the correct protocol: Query, JSON 1.1, REST JSON, or REST XML)
3. Add a Service (@ApplicationScoped) and model POJOs
4. Add a <Svc>ServiceConfig interface and its accessor on ServicesConfig in EmulatorConfig.java
5. Register a ServiceDescriptor in ResolvedServiceCatalog. This is the only registration point: ServiceRegistry reads the catalog and has no registration API
6. Add floci.services.<key>.enabled to both src/main/resources/application.yml and src/test/resources/application.yml
7. Wire controller/handler dispatch for the service (JSON 1.1 handlers are injected into AwsJson11Controller)
8. Obtain storage through StorageFactory and implement Resettable; list any static Random or SecureRandom field under --initialize-at-run-time in application.yml
9. Add *ServiceTest.java and *IntegrationTest.java tests
10. Document it: docs/services/<service>.md, a mkdocs.yml nav entry, a Service Matrix row in docs/services/index.md, and a row in the README category table
11. Register the handler in tools/docs/services.yaml, then run make docs-sync and make docs-check
12. Add a client factory in the compat suite's TestFixtures and a <Svc>Test under compatibility-tests/sdk-test-java

ServiceRegistry, ServiceEnabledFilter, and StorageFactory resolve service metadata from the descriptor catalog. Adding a service should not require new service-keyed switch statements in those consumers. make docs-check gates steps 10 and 11: a registered service with no matrix row, a docs/services page with no matrix row, and a stale action table all fail CI.

Always implement the real AWS wire protocol. Never invent custom endpoints. The AWS SDK must work against Floci without modification.

Adding a CloudFormation Resource Type

CloudFormation resource types live in per-service provisioner classes, not in CloudFormationResourceProvisioner. That class is a legacy monolith being dismantled, so please do not add cases to it. If the service you need already has a *CfnProvisioner, add your type there; otherwise create one.

1. Create services/cloudformation/provisioners/<Service>CfnProvisioner.java, annotate it @ApplicationScoped, and inject only the service it wraps. Registration is automatic: CloudFormationResourceRegistry discovers it via CDI. (Forgetting @ApplicationScoped compiles and unit-tests green, but the type is never wired.)
2. Implement resourceTypes() returning every AWS::* type the class serves, and provision(...). When you serve more than one type, switch on resource.getResourceType().
3. In provision, set both:
   • resource.setPhysicalId(...): this is what Ref resolves to
   • resource.getAttributes().put("Name", value) for every Fn::GetAtt attribute, a separate map. Forgetting it does not fail: Fn::GetAtt silently resolves to the literal string "LogicalId.Attr". Take the attribute names from the resource's registry schema under local/aws/cfn-resource-schemas/us-east-1/ (readOnlyProperties).
4. provision is also the update path. On UpdateStack it is called again with the previous physical id and attributes already set on the resource. Use ctx.isUpdate() and ctx.priorPhysicalId() rather than reading the id back off the resource: provision assigns the new id as it works, so a resource-derived check changes meaning mid-method. Update in place rather than creating unconditionally, which would otherwise throw AlreadyExists or orphan the old resource.
5. Override delete(...) if the type has a backing delete. Deleting a resource that is already gone should be tolerated: CfnDeletes.safeDelete does this, taking the specific error codes that mean "already gone" (never a catch-all: a real failure such as BucketNotEmpty must propagate so the stack reports DELETE_FAILED). If the delete needs more than the physical id (a create-time attribute such as a rule's event bus), override delete(StackResource, String) instead, which receives the whole resource.
6. Register the type in src/test/resources/cloudformation/supported-resource-types.tsv (type<TAB>YourCfnProvisioner). CfnResourceInventoryTest compares that file against the CDI-resolved registry, so it fails if you forget, which is also what catches a missing @ApplicationScoped.
7. Make your provisioner reachable from CfnProvisionerFixture if it takes a single service. That is three edits, not one: a private <Svc>Service field on Builder, a public Builder <svc>(<Svc>Service v) setter for it, and a construction arm in inferredProvisioners(). Tests name a service and the fixture wires the matching provisioner; without all three, a test exercising your type silently falls through to the stub arm instead. The setter is the step that gets missed: a field nothing can assign stays null, so its construction arm never runs. CfnProvisionerFixtureTest fails if the provisioner cannot be reached through the public builder.
8. Add a focused unit test (mock only your service, see SqsCfnProvisioner's test) and an integration test. Assert the specific Fn::GetAtt attribute keys, not just CREATE_COMPLETE: an unmapped type is stubbed out as a successful no-op, so a status-only assertion passes even when nothing was provisioned.
9. Run make docs-sync to regenerate the resource-type table in docs/services/cloudformation.md, and commit the result. Do not hand-edit that table: it is generated from the inventory in step 6. Presentation (service label, ordering, notes) lives in tools/docs/cfn_resource_types.yaml.
10. If your type has a schema readOnlyProperties entry you cannot set, add a row to src/test/resources/cloudformation/getatt-attribute-gaps.tsv with the reason. CfnSchemaCoverageTest requires every unset attribute to be either fixed or recorded, so "not emulated" stays distinguishable from "forgotten".

SqsCfnProvisioner is the smallest reference implementation; Ec2LaunchTemplateCfnProvisioner shows update-in-place and replacement handling; LogsCfnProvisioner shows a full reconcile-vs-replace update path.

Pull Request Guidelines

1. Branch off main: git checkout -b feature/my-feature
2. Open a PR targeting main.
3. CI runs tests automatically. All checks must pass before merge.
4. Keep PRs focused: one feature or fix per PR.
5. Reference any related issues in the PR description.
6. Keep at most 5 open PRs at a time. A bot leaves an advisory note and an over-pr-limit label on PRs opened beyond that. Nothing gets closed or blocked, but please land or close your existing PRs before opening more.

Docker images are built on contributor PRs only for the compatibility suite (.github/workflows/compatibility.yml, on changes under src/** and the compat test trees) and are never published, so merging to main is always cheap.

Release Process (maintainers)

Stable releases ship on the 1st and 3rd Tuesday of each month. Merging to main does not cut a release: the change rides the next train, and reaches the nightly image on the next nightly build.

Releases are cut from main with the Release Cut workflow (Actions → Release Cut → Run workflow). semantic-release analyzes the Conventional Commits since the last tag, bumps pom.xml, regenerates CHANGELOG.md, commits, tags, and publishes the GitHub Release; the tag push triggers the Docker publish pipeline. Use the dry-run input to preview the next version and notes without releasing.

CHANGELOG.md is generated. Do not edit it by hand. Your Conventional Commit message is the changelog entry. Genuine corrections to the file require the changelog-edit label on the PR.

Testing Policy for Pull Requests

Floci accepts pull requests only when the test coverage is appropriate for the type of change being proposed.

As a project policy:

• Pull requests that introduce new behavior must include tests that validate that behavior.
• Pull requests that fix bugs should include a regression test whenever the bug can be covered realistically.
• Pull requests that modify runtime logic, request handling, persistence behavior, protocol compatibility, or service responses are expected to include updated or additional tests.
• Pull requests that do not change observable behavior, such as documentation updates, formatting, comments, dependency housekeeping, or low-risk internal refactors, may not require new tests.
• Even when no new tests are needed, the existing test suite must still pass.

If a pull request does not include new tests, the author should explain why in the PR description. Valid reasons may include:

• no functional behavior changed
• existing tests already cover the change
• the change is not meaningfully testable in isolation

Maintainers may request additional or more targeted test coverage before approving a PR.

CI runs automatically on every pull request, and build/test checks must pass before merge.

Documentation: Action Tables

The Supported Actions tables in docs/services/*.md are generated from handler source, so they cannot drift from the code. The action list comes from the handler (case "X" -> arms or REST controller methods); the Description column is hand-written and preserved across regeneration, keyed by action name.

• Do not hand-edit the action rows between the <!-- floci:actions:start --> and <!-- floci:actions:end --> markers. Edit the handler, then regenerate.
• After adding or changing a handler action, run make docs-sync and commit the updated doc alongside your code. Fill in the - placeholder description for any new row.
• make docs-check (run in CI) fails if a registered service's table is out of date, or if a new switch handler is neither registered in tools/docs/services.yaml nor listed under deferred_handlers.
• make docs-test runs the tooling's unit tests.

Registering a new service's action table is one entry in tools/docs/services.yaml.

Reporting Security Issues

Please do not open public issues for security vulnerabilities. Report them privately by emailing the maintainer or using GitHub private vulnerability reporting.