Light, fluffy, and always free - The AWS Local Emulator alternative
docs: adopt AGENTS.md standard (#1225)
David Phillipsfbff3b2872dc
diff --git a/AGENT.md b/AGENT.mddeleted file mode 100644index f90f755fa4..0000000000--- a/AGENT.md+++ /dev/null@@ -1,355 +0,0 @@-Guidance for AI coding agents working in the Floci repository.--This file defines repository-specific operating rules for autonomous or semi-autonomous coding agents. Follow these instructions unless a maintainer explicitly tells you otherwise.-------## Project Overview--Floci is a Java-based local AWS emulator built on Quarkus.--Its goal is full AWS SDK and AWS CLI compatibility through real AWS wire protocols, not convenience APIs or simplified abstractions.--Floci acts as an open-source alternative to LocalStack Community.--- Port: 4566-- Stack:- - Java 25- - Quarkus 3.32.3- - JUnit 5- - RestAssured- - Jackson- - Docker integrations for Lambda, RDS, and ElastiCache-------## First Principles--When making changes, follow these priorities:--1. Preserve AWS protocol compatibility-2. Match AWS SDK and CLI behavior-3. Reuse existing Floci patterns-4. Prefer correctness over convenience-5. Keep changes narrow and testable--Critical rules:--- Do not introduce custom endpoint shapes-- Do not change request or response formats for convenience-- Do not perform broad refactors unless the task explicitly requires them-- Keep behavior aligned with AWS expectations and existing Floci conventions-------## Architecture--Floci follows a layered design:--- **Controller / Handler**- - Parses AWS protocol input- - Produces AWS-compatible responses--- **Service**- - Contains business logic- - Throws `AwsException`--- **Model**- - Domain objects--### Core Infrastructure--- `EmulatorConfig`-- `ServiceRegistry`-- `StorageBackend` + `StorageFactory`-- `AwsJson11Controller`-- `AwsQueryController`-- `AwsException` + `AwsExceptionMapper`-- `EmulatorLifecycle`-------## Package Layout--- `io.github.hectorvent.floci.config`-- `io.github.hectorvent.floci.core.common`-- `io.github.hectorvent.floci.core.storage`-- `io.github.hectorvent.floci.lifecycle`-- `io.github.hectorvent.floci.services.<service>`--Typical service structure:--- `services/<svc>/`- - `*Controller.java`- - `*Service.java`- - `model/`--Rule:-Copy an existing service pattern before introducing a new one.-------## AWS Protocol Rules--Floci must implement real AWS wire protocols.--| Protocol | Services | Request Format | Response Format | Implementation |-|----------|----------|----------------|-----------------|----------------|-| Query | SQS, SNS, IAM, STS, RDS, ElastiCache, CloudFormation, CloudWatch Metrics | form-encoded POST + `Action` | XML | `AwsQueryController` |-| JSON 1.1 | SSM, EventBridge, CloudWatch Logs, Kinesis, KMS, Cognito, Secrets Manager, ACM | POST + `X-Amz-Target` | JSON | `AwsJson11Controller` |-| REST JSON | Lambda, API Gateway, SES V2 | REST paths | JSON | JAX-RS |-| REST XML | S3 | REST paths | XML | JAX-RS |-| TCP | ElastiCache, RDS | raw protocol | native | proxies |--### Important exceptions--- CloudWatch Metrics supports both Query and JSON 1.1; handlers must remain aligned-- SQS and SNS may expose multiple compatibility paths; do not let them drift-- Cognito well-known endpoints are OIDC REST JSON endpoints, not AWS management APIs-- Data-plane protocols may use raw TCP sockets-- Management APIs should be validated with AWS SDK clients, not only handcrafted HTTP requests-------## XML / JSON Rules--- Use `XmlBuilder` for XML responses-- Use `XmlParser` for XML parsing; do not use regex-- Use `AwsNamespaces` constants-- JSON errors must follow AWS error structures-- Types returned directly from controllers must remain compatible with native-image reflection requirements-------## Storage Rules--Supported storage modes:--- `memory`-- `persistent`-- `hybrid`-- `wal`--Rules:--- Always use `StorageFactory`-- Do not instantiate storage implementations directly inside services-- Respect lifecycle hooks for load and flush behavior--Important nuance:--Configuration interfaces may declare fallback defaults, but `application.yml` defines effective runtime behavior. Treat repository YAML as the source of truth unless a task explicitly changes configuration semantics.--When adding storage-related behavior:--1. Update `EmulatorConfig`-2. Update main `application.yml`-3. Update test `application.yml`-4. Wire through `StorageFactory`-5. Verify lifecycle integration-------## Configuration Rules--Configuration lives under `floci.*`.--When adding config:--1. Add it to `EmulatorConfig`-2. Add it to main `application.yml`-3. Add it to test `application.yml` if needed-4. Update documentation if user-facing-5. Follow `FLOCI_*` environment variable conventions--Critical areas:--- `base-url`-- `hostname`-- region and account defaults-- port ranges-- persistence paths-- Docker networking-------## Build & Run-- ./mvnw quarkus:dev- ./mvnw test- ./mvnw clean package- ./mvnw clean package -DskipTests--### Focused tests-- ./mvnw test -Dtest=SsmIntegrationTest- ./mvnw test -Dtest=SsmIntegrationTest#putParameter-------## Compatibility Project--Compatibility test suite: `./compatibility-tests/`--Guidelines:--- Prefer AWS SDK clients over raw HTTP for management-plane validation-- Use this suite when changes may affect real SDK behavior-------## Testing Rules--### Conventions--- Unit tests: `*ServiceTest.java`-- Integration tests: `*IntegrationTest.java`-- Prefer package-private constructors for testability-- Integration tests may use ordered execution when stateful behavior requires it--### Expectations--- Test any behavior affecting AWS compatibility-- Do not rely only on manual HTTP testing-- Prefer SDK-based validation where possible--### When touching protocol behavior--If a change affects request parsing, response shape, error handling, persistence semantics, URL generation, or service enablement:--1. Add or update automated tests-2. Prefer SDK-based verification where possible-3. Check compatibility across alternate protocol paths-4. Document intentional deviations clearly-------## Error Handling--- Services should throw `AwsException`-- Query and REST XML flows should use `AwsExceptionMapper`-- JSON 1.1 flows should return structured AWS error responses where required-- Controller return types must remain reflection-safe-------## Service Implementation Pattern--When adding functionality:--1. Identify the AWS protocol-2. Reuse an existing service pattern-3. Keep controllers thin-4. Use `AwsException` for domain errors-5. Reuse shared utilities-6. Update config, storage, docs, and tests together-7. Validate behavior against AWS SDK expectations-------## Adding a New AWS Service--1. Create a package under `services/`-2. Add:- - Controller- - Service- - `model/`-3. Register the service in `ServiceRegistry`-4. Add config to `EmulatorConfig`-5. Add YAML config in main and test config files-6. Wire storage through `StorageFactory`-7. Add tests-8. Update documentation-------## Code Style--- Use constructor injection-- Prefer self-explanatory code over comments-- Avoid unnecessary comments-- Always use braces in conditionals-- Follow existing project patterns-- Use modern Java features only when they improve clarity-------## Logging--- Use JBoss Logging-- Keep logs structured-- Avoid noisy logs in hot paths-------## Pull Request Guidelines--- Keep changes focused-- Avoid unrelated refactors-- Preserve behavior unless the task explicitly requires change-- Update docs when necessary-- Explain missing tests when behavior changed but no automated coverage was added--Conventional commits:--- `feat:`-- `fix:`-- `perf:`-- `docs:`-- `chore:`--Do not add `Co-Authored-By` trailers for AI tools in commit messages. Keep attribution limited to human contributors.-------## Release Awareness--- Changes merged into `main` do not automatically imply a stable release-- Release branches define stable release lines-- Tags trigger publishing workflows--Treat release workflows as critical infrastructure.-------## Agent Workflow--### Before editing--1. Identify service and protocol-2. Locate an existing implementation to mirror-3. Check config impact-4. Check storage impact-5. Check documentation impact-6. Define the minimal useful test plan--### Before finishing--1. Run relevant tests-2. Validate protocol behavior-3. Ensure no custom endpoints were introduced-4. Verify config and docs updates-------## Common Mistakes--- Creating non-AWS endpoints-- Bypassing `StorageFactory`-- Changing wire formats without tests-- Forgetting YAML updates-- Producing inconsistent URLs or ARNs-- Testing only with raw HTTP-- Introducing unnecessary new patterns-------## Human Handoff--If behavior is unclear:--1. Prefer AWS behavior-2. Then existing Floci behavior-3. Then compatibility test expectations--If a task would require broad architectural changes, stop and surface the tradeoffs instead of refactoring across services blindly.diff --git a/AGENT.md b/AGENT.mdnew file mode 120000index 0000000000..47dc3e3d86--- /dev/null+++ b/AGENT.md@@ -0,0 +1 @@+AGENTS.md\ No newline at end of filediff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000000..f90f755fa4--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,355 @@+Guidance for AI coding agents working in the Floci repository.++This file defines repository-specific operating rules for autonomous or semi-autonomous coding agents. Follow these instructions unless a maintainer explicitly tells you otherwise.++---++## Project Overview++Floci is a Java-based local AWS emulator built on Quarkus.++Its goal is full AWS SDK and AWS CLI compatibility through real AWS wire protocols, not convenience APIs or simplified abstractions.++Floci acts as an open-source alternative to LocalStack Community.++- Port: 4566+- Stack:+ - Java 25+ - Quarkus 3.32.3+ - JUnit 5+ - RestAssured+ - Jackson+ - Docker integrations for Lambda, RDS, and ElastiCache++---++## First Principles++When making changes, follow these priorities:++1. Preserve AWS protocol compatibility+2. Match AWS SDK and CLI behavior+3. Reuse existing Floci patterns+4. Prefer correctness over convenience+5. Keep changes narrow and testable++Critical rules:++- Do not introduce custom endpoint shapes+- Do not change request or response formats for convenience+- Do not perform broad refactors unless the task explicitly requires them+- Keep behavior aligned with AWS expectations and existing Floci conventions++---++## Architecture++Floci follows a layered design:++- **Controller / Handler**+ - Parses AWS protocol input+ - Produces AWS-compatible responses++- **Service**+ - Contains business logic+ - Throws `AwsException`++- **Model**+ - Domain objects++### Core Infrastructure++- `EmulatorConfig`+- `ServiceRegistry`+- `StorageBackend` + `StorageFactory`+- `AwsJson11Controller`+- `AwsQueryController`+- `AwsException` + `AwsExceptionMapper`+- `EmulatorLifecycle`++---++## Package Layout++- `io.github.hectorvent.floci.config`+- `io.github.hectorvent.floci.core.common`+- `io.github.hectorvent.floci.core.storage`+- `io.github.hectorvent.floci.lifecycle`+- `io.github.hectorvent.floci.services.<service>`++Typical service structure:++- `services/<svc>/`+ - `*Controller.java`+ - `*Service.java`+ - `model/`++Rule:+Copy an existing service pattern before introducing a new one.++---++## AWS Protocol Rules++Floci must implement real AWS wire protocols.++| Protocol | Services | Request Format | Response Format | Implementation |+|----------|----------|----------------|-----------------|----------------|+| Query | SQS, SNS, IAM, STS, RDS, ElastiCache, CloudFormation, CloudWatch Metrics | form-encoded POST + `Action` | XML | `AwsQueryController` |+| JSON 1.1 | SSM, EventBridge, CloudWatch Logs, Kinesis, KMS, Cognito, Secrets Manager, ACM | POST + `X-Amz-Target` | JSON | `AwsJson11Controller` |+| REST JSON | Lambda, API Gateway, SES V2 | REST paths | JSON | JAX-RS |+| REST XML | S3 | REST paths | XML | JAX-RS |+| TCP | ElastiCache, RDS | raw protocol | native | proxies |++### Important exceptions++- CloudWatch Metrics supports both Query and JSON 1.1; handlers must remain aligned+- SQS and SNS may expose multiple compatibility paths; do not let them drift+- Cognito well-known endpoints are OIDC REST JSON endpoints, not AWS management APIs+- Data-plane protocols may use raw TCP sockets+- Management APIs should be validated with AWS SDK clients, not only handcrafted HTTP requests++---++## XML / JSON Rules++- Use `XmlBuilder` for XML responses+- Use `XmlParser` for XML parsing; do not use regex+- Use `AwsNamespaces` constants+- JSON errors must follow AWS error structures+- Types returned directly from controllers must remain compatible with native-image reflection requirements++---++## Storage Rules++Supported storage modes:++- `memory`+- `persistent`+- `hybrid`+- `wal`++Rules:++- Always use `StorageFactory`+- Do not instantiate storage implementations directly inside services+- Respect lifecycle hooks for load and flush behavior++Important nuance:++Configuration interfaces may declare fallback defaults, but `application.yml` defines effective runtime behavior. Treat repository YAML as the source of truth unless a task explicitly changes configuration semantics.++When adding storage-related behavior:++1. Update `EmulatorConfig`+2. Update main `application.yml`+3. Update test `application.yml`+4. Wire through `StorageFactory`+5. Verify lifecycle integration++---++## Configuration Rules++Configuration lives under `floci.*`.++When adding config:++1. Add it to `EmulatorConfig`+2. Add it to main `application.yml`+3. Add it to test `application.yml` if needed+4. Update documentation if user-facing+5. Follow `FLOCI_*` environment variable conventions++Critical areas:++- `base-url`+- `hostname`+- region and account defaults+- port ranges+- persistence paths+- Docker networking++---++## Build & Run++ ./mvnw quarkus:dev+ ./mvnw test+ ./mvnw clean package+ ./mvnw clean package -DskipTests++### Focused tests++ ./mvnw test -Dtest=SsmIntegrationTest+ ./mvnw test -Dtest=SsmIntegrationTest#putParameter++---++## Compatibility Project++Compatibility test suite: `./compatibility-tests/`++Guidelines:++- Prefer AWS SDK clients over raw HTTP for management-plane validation+- Use this suite when changes may affect real SDK behavior++---++## Testing Rules++### Conventions++- Unit tests: `*ServiceTest.java`+- Integration tests: `*IntegrationTest.java`+- Prefer package-private constructors for testability+- Integration tests may use ordered execution when stateful behavior requires it++### Expectations++- Test any behavior affecting AWS compatibility+- Do not rely only on manual HTTP testing+- Prefer SDK-based validation where possible++### When touching protocol behavior++If a change affects request parsing, response shape, error handling, persistence semantics, URL generation, or service enablement:++1. Add or update automated tests+2. Prefer SDK-based verification where possible+3. Check compatibility across alternate protocol paths+4. Document intentional deviations clearly++---++## Error Handling++- Services should throw `AwsException`+- Query and REST XML flows should use `AwsExceptionMapper`+- JSON 1.1 flows should return structured AWS error responses where required+- Controller return types must remain reflection-safe++---++## Service Implementation Pattern++When adding functionality:++1. Identify the AWS protocol+2. Reuse an existing service pattern+3. Keep controllers thin+4. Use `AwsException` for domain errors+5. Reuse shared utilities+6. Update config, storage, docs, and tests together+7. Validate behavior against AWS SDK expectations++---++## Adding a New AWS Service++1. Create a package under `services/`+2. Add:+ - Controller+ - Service+ - `model/`+3. Register the service in `ServiceRegistry`+4. Add config to `EmulatorConfig`+5. Add YAML config in main and test config files+6. Wire storage through `StorageFactory`+7. Add tests+8. Update documentation++---++## Code Style++- Use constructor injection+- Prefer self-explanatory code over comments+- Avoid unnecessary comments+- Always use braces in conditionals+- Follow existing project patterns+- Use modern Java features only when they improve clarity++---++## Logging++- Use JBoss Logging+- Keep logs structured+- Avoid noisy logs in hot paths++---++## Pull Request Guidelines++- Keep changes focused+- Avoid unrelated refactors+- Preserve behavior unless the task explicitly requires change+- Update docs when necessary+- Explain missing tests when behavior changed but no automated coverage was added++Conventional commits:++- `feat:`+- `fix:`+- `perf:`+- `docs:`+- `chore:`++Do not add `Co-Authored-By` trailers for AI tools in commit messages. Keep attribution limited to human contributors.++---++## Release Awareness++- Changes merged into `main` do not automatically imply a stable release+- Release branches define stable release lines+- Tags trigger publishing workflows++Treat release workflows as critical infrastructure.++---++## Agent Workflow++### Before editing++1. Identify service and protocol+2. Locate an existing implementation to mirror+3. Check config impact+4. Check storage impact+5. Check documentation impact+6. Define the minimal useful test plan++### Before finishing++1. Run relevant tests+2. Validate protocol behavior+3. Ensure no custom endpoints were introduced+4. Verify config and docs updates++---++## Common Mistakes++- Creating non-AWS endpoints+- Bypassing `StorageFactory`+- Changing wire formats without tests+- Forgetting YAML updates+- Producing inconsistent URLs or ARNs+- Testing only with raw HTTP+- Introducing unnecessary new patterns++---++## Human Handoff++If behavior is unclear:++1. Prefer AWS behavior+2. Then existing Floci behavior+3. Then compatibility test expectations++If a task would require broad architectural changes, stop and surface the tradeoffs instead of refactoring across services blindly.