Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
deleted file mode 100644
index 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.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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.