Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(docs): generate Supported Actions tables from handler source (#1641)

TiM7d70f64162d4
diff --git a/.github/workflows/docs-actions.yml b/.github/workflows/docs-actions.yml
new file mode 100644
index 0000000000..8a5f047d42
--- /dev/null
+++ b/.github/workflows/docs-actions.yml
@@ -0,0 +1,52 @@
+name: Docs Action Tables
+
+# Keeps the generated "Supported Actions" tables in docs/services/*.md in sync with
+# handler source. Runs on handler changes (which can add/remove actions) and on doc or
+# tooling changes. Python-only, so it is fast and independent of the Java build job.
+
+on:
+ pull_request:
+ paths:
+ - 'src/main/**'
+ - 'docs/services/**'
+ - 'tools/docs/**'
+ - 'Makefile'
+ - '.github/workflows/docs-actions.yml'
+ push:
+ branches:
+ - main
+ paths:
+ - 'src/main/**'
+ - 'docs/services/**'
+ - 'tools/docs/**'
+ - 'Makefile'
+ - '.github/workflows/docs-actions.yml'
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ action-tables:
+ name: Action tables in sync
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/[email protected]
+
+ - name: Set up Python
+ uses: actions/setup-python@v6
+ with:
+ python-version: "3.x"
+
+ - name: Install tooling deps
+ run: pip install -r tools/docs/requirements.txt
+
+ - name: Run action-table tests
+ run: make docs-test
+
+ - name: Check action tables are in sync
+ run: make docs-check
diff --git a/.gitignore b/.gitignore
index 7a859fd4b6..47347747eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,3 +32,7 @@ test-results.xml
test-results
scripts/node_modules/
+
+# Python tooling caches
+__pycache__/
+*.pyc
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1560ff4421..02f7a3bcee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -212,6 +212,25 @@ Maintainers may request additional or more targeted test coverage before approvi
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 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](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability).
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000..3894362783
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,27 @@
+# Floci repo tasks.
+#
+# Action-table docs: docs/services/*.md "Supported Actions" tables are generated
+# from handler source. See tools/docs/.
+
+PYTHON ?= python3
+
+.PHONY: docs-sync docs-check docs-test
+
+docs-sync: ## Regenerate the action tables in docs/services from handler source (in place)
+ $(PYTHON) tools/docs/regen_action_docs.py
+
+docs-check: ## CI gate: regenerate and fail if anything is stale or a handler is unregistered
+ @$(PYTHON) tools/docs/regen_action_docs.py --strict || { \
+ echo ""; \
+ echo "error: action-table regeneration reported problems (see warnings above)."; \
+ exit 1; \
+ }
+ @git diff --exit-code -- docs/ || { \
+ echo ""; \
+ echo "error: docs/services action tables are out of date."; \
+ echo " Run 'make docs-sync' and commit the result."; \
+ exit 1; \
+ }
+
+docs-test: ## Run the action-table tooling tests
+ $(PYTHON) -m pytest tools/docs -q
diff --git a/docs/services/acm.md b/docs/services/acm.md
index f8047c488d..cdda33df06 100644
--- a/docs/services/acm.md
+++ b/docs/services/acm.md
@@ -5,20 +5,22 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `RequestCertificate` | Request a new certificate (auto-issued for emulation) |
| `DescribeCertificate` | Get certificate details and validation status |
| `GetCertificate` | Retrieve the certificate and chain in PEM format |
| `ListCertificates` | List all certificates with optional status filtering |
| `DeleteCertificate` | Delete a certificate |
+| `ImportCertificate` | - |
+| `ExportCertificate` | Export certificate with encrypted private key (PRIVATE type only) |
| `AddTagsToCertificate` | Add tags to a certificate |
-| `RemoveTagsFromCertificate` | Remove tags from a certificate |
| `ListTagsForCertificate` | List tags for a certificate |
-| `ExportCertificate` | Export certificate with encrypted private key (PRIVATE type only) |
+| `RemoveTagsFromCertificate` | Remove tags from a certificate |
| `GetAccountConfiguration` | Get account-level ACM settings |
| `PutAccountConfiguration` | Update account-level ACM settings |
-| `RenewCertificate` | Trigger certificate renewal |
+<!-- floci:actions:end -->
## Emulation Behavior
diff --git a/docs/services/athena.md b/docs/services/athena.md
index e80df78322..48da8fdca6 100644
--- a/docs/services/athena.md
+++ b/docs/services/athena.md
@@ -7,17 +7,24 @@ Floci emulates Amazon Athena with **real SQL execution** powered by a [floci-duc
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `StartQueryExecution` | Submits a SQL query; executed asynchronously via DuckDB |
| `GetQueryExecution` | Returns query status (`QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`) |
| `GetQueryResults` | Returns the result set for a completed query |
| `ListQueryExecutions` | Returns a list of past query executions |
| `StopQueryExecution` | Cancels a running query |
-| `CreateWorkGroup` | Creates a new workgroup |
| `GetWorkGroup` | Returns information about a workgroup |
-| `DeleteWorkGroup` | Deletes a workgroup |
| `ListWorkGroups` | Lists all workgroups |
+| `CreateWorkGroup` | Creates a new workgroup |
+| `ListDataCatalogs` | - |
+| `GetDataCatalog` | - |
+| `ListDatabases` | - |
+| `ListTableMetadata` | - |
+| `GetTableMetadata` | - |
+| `DeleteWorkGroup` | Deletes a workgroup |
+<!-- floci:actions:end -->
## How it works
diff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.md
index 9f2944a54e..5060f04d34 100644
--- a/docs/services/cloudformation.md
+++ b/docs/services/cloudformation.md
@@ -5,26 +5,28 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
+| `DescribeStacks` | Get stack status and outputs |
| `CreateStack` | Deploy a CloudFormation template |
| `UpdateStack` | Update an existing stack |
| `DeleteStack` | Delete a stack and its resources |
-| `DescribeStacks` | Get stack status and outputs |
-| `ListStacks` | List stacks by status |
+| `CreateChangeSet` | Create a change set |
+| `DescribeChangeSet` | Get change set details (no computed diff/preview) |
+| `ExecuteChangeSet` | Apply a change set |
+| `DeleteChangeSet` | Delete a change set |
+| `ListChangeSets` | List change sets for a stack |
| `DescribeStackEvents` | Get stack creation/update event history |
| `DescribeStackResources` | Get all resources in a stack |
-| `DescribeStackResource` | Get a specific stack resource |
| `ListStackResources` | List resource summaries |
| `GetTemplate` | Retrieve the template body |
| `ValidateTemplate` | Accepted; returns success without validating (stub) |
-| `CreateChangeSet` | Create a change set |
-| `DescribeChangeSet` | Get change set details (no computed diff/preview) |
-| `ExecuteChangeSet` | Apply a change set |
-| `ListChangeSets` | List change sets for a stack |
-| `DeleteChangeSet` | Delete a change set |
+| `ListStacks` | List stacks by status |
+| `ListExports` | - |
| `SetStackPolicy` | Accepted; no-op (stub — stack policies are not enforced) |
| `GetStackPolicy` | Accepted; returns an empty policy (stub) |
+| `DescribeStackResource` | Get a specific stack resource |
| `CreateStackSet` | Create a stack set from a template |
| `DescribeStackSet` | Get stack set details |
| `ListStackSets` | List stack sets |
@@ -32,8 +34,11 @@
| `DeleteStackSet` | Delete an empty stack set |
| `CreateStackInstances` | Provision instances into target accounts/regions |
| `ListStackInstances` | List instances (optionally filtered by account/region) |
+| `DescribeStackInstance` | - |
| `DeleteStackInstances` | Remove instances and their resources |
| `ListStackSetOperations` | List operations performed on a stack set |
+| `DescribeStackSetOperation` | - |
+<!-- floci:actions:end -->
## Supported Resource Types
diff --git a/docs/services/cloudtrail.md b/docs/services/cloudtrail.md
index 1ac3979cb8..8b0279c94f 100644
--- a/docs/services/cloudtrail.md
+++ b/docs/services/cloudtrail.md
@@ -8,16 +8,19 @@ Floci emulates the AWS CloudTrail management API. Trails, their event selectors,
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateTrail` | Creates a trail and returns its ARN |
| `UpdateTrail` | Updates the settings of an existing trail |
-| `DeleteTrail` | Deletes a trail |
| `DescribeTrails` | Returns the settings for one or more trails |
-| `GetTrailStatus` | Returns the logging status of a trail |
| `StartLogging` | Starts logging for a trail |
| `StopLogging` | Stops logging for a trail |
+| `DeleteTrail` | Deletes a trail |
+| `GetTrailStatus` | Returns the logging status of a trail |
| `PutEventSelectors` | Configures the event selectors for a trail |
+| `LookupEvents` | - |
+<!-- floci:actions:end -->
## Example
diff --git a/docs/services/docdb.md b/docs/services/docdb.md
index 025b1af734..b61480fb05 100644
--- a/docs/services/docdb.md
+++ b/docs/services/docdb.md
@@ -16,8 +16,9 @@ The management API shares the RDS Query endpoint (`POST /` with an `Action=` par
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|--------|-------------|
+| --- | --- |
| `CreateDBCluster` | Create a DocumentDB cluster and start a MongoDB container |
| `DescribeDBClusters` | List clusters and their connection details |
| `DeleteDBCluster` | Stop and remove a cluster (must have no instances) |
@@ -26,6 +27,7 @@ The management API shares the RDS Query endpoint (`POST /` with an `Action=` par
| `DescribeDBInstances` | List instances |
| `DeleteDBInstance` | Remove an instance from a cluster |
| `ModifyDBInstance` | Update instance class or IAM auth setting |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/elasticache.md b/docs/services/elasticache.md
index 3cf6f6335b..d56f20716c 100644
--- a/docs/services/elasticache.md
+++ b/docs/services/elasticache.md
@@ -8,16 +8,22 @@ Floci manages real Valkey/Redis Docker containers and proxies TCP connections to
## Supported Management Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
+| `ValidateIamAuthToken` | Validate an IAM auth token (data-plane auth) |
| `CreateReplicationGroup` | Start a new Redis/Valkey cluster |
| `DescribeReplicationGroups` | List clusters and their connection info |
+| `ModifyReplicationGroup` | - |
| `DeleteReplicationGroup` | Stop and remove a cluster |
| `CreateUser` | Create an ElastiCache IAM user |
| `DescribeUsers` | List ElastiCache users |
| `ModifyUser` | Update user access strings |
| `DeleteUser` | Remove an ElastiCache user |
-| `ValidateIamAuthToken` | Validate an IAM auth token (data-plane auth) |
+| `CreateCacheCluster` | - |
+| `DescribeCacheClusters` | - |
+| `DeleteCacheCluster` | - |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/emr.md b/docs/services/emr.md
index b5d6c07f9d..fac5ec4d7f 100644
--- a/docs/services/emr.md
+++ b/docs/services/emr.md
@@ -8,32 +8,34 @@ Floci emulates the Amazon EMR (Elastic MapReduce) management API. Clusters (job
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `RunJobFlow` | Creates a new cluster (job flow) and returns its `JobFlowId` |
| `DescribeCluster` | Returns the configuration and status of a cluster |
| `ListClusters` | Lists clusters, filterable by state and creation time |
-| `ModifyCluster` | Updates cluster-level settings such as step concurrency |
| `TerminateJobFlows` | Terminates one or more clusters |
| `SetTerminationProtection` | Enables or disables termination protection |
-| `SetKeepJobFlowAliveWhenNoSteps` | Controls auto-termination when steps complete |
| `SetVisibleToAllUsers` | Sets cluster visibility for the account |
+| `SetKeepJobFlowAliveWhenNoSteps` | Controls auto-termination when steps complete |
| `SetUnhealthyNodeReplacement` | Toggles unhealthy-node replacement |
+| `ModifyCluster` | Updates cluster-level settings such as step concurrency |
+| `AddJobFlowSteps` | Adds one or more steps to a cluster |
+| `DescribeStep` | Returns the detail and status of a single step |
+| `ListSteps` | Lists the steps of a cluster, filterable by state |
+| `CancelSteps` | Cancels pending steps |
| `AddInstanceGroups` | Adds instance groups to a running cluster |
| `ListInstanceGroups` | Lists the instance groups of a cluster |
| `AddInstanceFleet` | Adds an instance fleet to a cluster |
| `ListInstanceFleets` | Lists the instance fleets of a cluster |
| `ListInstances` | Lists the EC2 instances of a cluster |
-| `AddJobFlowSteps` | Adds one or more steps to a cluster |
-| `ListSteps` | Lists the steps of a cluster, filterable by state |
-| `DescribeStep` | Returns the detail and status of a single step |
-| `CancelSteps` | Cancels pending steps |
| `CreateSecurityConfiguration` | Creates a named security configuration |
| `DescribeSecurityConfiguration` | Returns a security configuration |
| `DeleteSecurityConfiguration` | Deletes a security configuration |
| `ListSecurityConfigurations` | Lists all security configurations |
| `AddTags` | Adds tags to a cluster |
| `RemoveTags` | Removes tags from a cluster |
+<!-- floci:actions:end -->
## Example
diff --git a/docs/services/eventbridge.md b/docs/services/eventbridge.md
index 9619f981ae..8638cf5bf0 100644
--- a/docs/services/eventbridge.md
+++ b/docs/services/eventbridge.md
@@ -5,8 +5,9 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateEventBus` | Create a custom event bus |
| `DeleteEventBus` | Delete an event bus |
| `DescribeEventBus` | Get event bus details |
@@ -23,6 +24,21 @@
| `ListTargetsByRule` | List targets for a rule |
| `PutEvents` | Publish custom events to an event bus |
| `TestEventPattern` | Test whether a sample event matches a given pattern (no targets fired) |
+| `ListTagsForResource` | - |
+| `TagResource` | - |
+| `UntagResource` | - |
+| `PutPermission` | - |
+| `RemovePermission` | - |
+| `CreateArchive` | - |
+| `DescribeArchive` | - |
+| `UpdateArchive` | - |
+| `DeleteArchive` | - |
+| `ListArchives` | - |
+| `StartReplay` | - |
+| `DescribeReplay` | - |
+| `CancelReplay` | - |
+| `ListReplays` | - |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/firehose.md b/docs/services/firehose.md
index e2d9575975..6b188d53a6 100644
--- a/docs/services/firehose.md
+++ b/docs/services/firehose.md
@@ -7,14 +7,20 @@ Floci emulates Amazon Data Firehose for streaming data ingestion and delivery to
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateDeliveryStream` | Creates a new delivery stream |
+| `UpdateDestination` | - |
| `DescribeDeliveryStream` | Returns metadata about a stream |
| `ListDeliveryStreams` | Lists all delivery streams |
| `DeleteDeliveryStream` | Deletes a delivery stream |
| `PutRecord` | Writes a single data record to the stream |
| `PutRecordBatch` | Writes multiple data records to the stream |
+| `TagDeliveryStream` | - |
+| `UntagDeliveryStream` | - |
+| `ListTagsForDeliveryStream` | - |
+<!-- floci:actions:end -->
## How it works
diff --git a/docs/services/kinesis.md b/docs/services/kinesis.md
index 2031b759b6..7555e0ee01 100644
--- a/docs/services/kinesis.md
+++ b/docs/services/kinesis.md
@@ -5,8 +5,9 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateStream` | Create a stream |
| `DeleteStream` | Delete a stream |
| `ListStreams` | List all streams |
@@ -17,19 +18,24 @@
| `DescribeStreamConsumer` | Get consumer details |
| `ListStreamConsumers` | List consumers for a stream |
| `SubscribeToShard` | Subscribe to a shard for enhanced fan-out |
+| `AddTagsToStream` | Tag a stream |
+| `RemoveTagsFromStream` | Remove tags |
+| `ListTagsForStream` | List tags |
+| `StartStreamEncryption` | Enable KMS encryption |
+| `StopStreamEncryption` | Disable encryption |
+| `SplitShard` | Split a shard into two |
+| `MergeShards` | Merge two adjacent shards |
| `PutRecord` | Write a single record |
| `PutRecords` | Write up to 500 records |
| `GetShardIterator` | Get an iterator for reading |
| `GetRecords` | Read records from a shard |
-| `SplitShard` | Split a shard into two |
-| `MergeShards` | Merge two adjacent shards |
-| `AddTagsToStream` | Tag a stream |
-| `RemoveTagsFromStream` | Remove tags |
-| `ListTagsForStream` | List tags |
+| `ListShards` | - |
| `IncreaseStreamRetentionPeriod` | Increase retention up to 8760 hours (365 days) |
| `DecreaseStreamRetentionPeriod` | Decrease retention down to 24 hours |
-| `StartStreamEncryption` | Enable KMS encryption |
-| `StopStreamEncryption` | Disable encryption |
+| `EnableEnhancedMonitoring` | - |
+| `DisableEnhancedMonitoring` | - |
+| `UpdateStreamMode` | - |
+<!-- floci:actions:end -->
## Stream Addressing
diff --git a/docs/services/kms.md b/docs/services/kms.md
index 448c56263e..6c37207957 100644
--- a/docs/services/kms.md
+++ b/docs/services/kms.md
@@ -5,13 +5,19 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateKey` | Create a new KMS key |
| `GenerateRandom` | Generate random bytes |
| `GetPublicKey` | Get public key material for asymmetric keys |
| `DescribeKey` | Get key metadata |
| `ListKeys` | List all keys |
+| `CreateGrant` | Create a grant for a KMS key |
+| `ListGrants` | List grants for a KMS key |
+| `ListRetirableGrants` | List grants retirable by a principal |
+| `RevokeGrant` | Revoke (administratively delete) a grant |
+| `RetireGrant` | Retire a grant (token- or key+grant-based) |
| `Encrypt` | Encrypt plaintext with a key |
| `Decrypt` | Decrypt ciphertext |
| `ReEncrypt` | Re-encrypt under a different key |
@@ -26,8 +32,6 @@
| `ListAliases` | List all aliases |
| `ScheduleKeyDeletion` | Mark a key for deletion |
| `CancelKeyDeletion` | Cancel pending deletion |
-| `EnableKey` | Enable a key |
-| `DisableKey` | Disable a key |
| `TagResource` | Tag a key |
| `UntagResource` | Remove tags |
| `ListResourceTags` | List tags |
@@ -37,12 +41,10 @@
| `GetKeyRotationStatus` | Check if automatic key rotation is enabled |
| `EnableKeyRotation` | Enable automatic key rotation (symmetric keys only) |
| `DisableKeyRotation` | Disable automatic key rotation |
+| `EnableKey` | Enable a key |
+| `DisableKey` | Disable a key |
| `RotateKeyOnDemand` | Rotate key material on demand (symmetric keys only) |
-| `CreateGrant` | Create a grant for a KMS key |
-| `ListGrants` | List grants for a KMS key |
-| `ListRetirableGrants` | List grants retirable by a principal |
-| `RevokeGrant` | Revoke (administratively delete) a grant |
-| `RetireGrant` | Retire a grant (token- or key+grant-based) |
+<!-- floci:actions:end -->
## Grant Support Scope
diff --git a/docs/services/memorydb.md b/docs/services/memorydb.md
index eea80a91a4..32db2c60ce 100644
--- a/docs/services/memorydb.md
+++ b/docs/services/memorydb.md
@@ -12,15 +12,23 @@ Set `FLOCI_SERVICES_MEMORYDB_MOCK=true` to manage clusters as control-plane-only
## Supported Management Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateCluster` | Start a new MemoryDB (Redis/Valkey) cluster |
| `DescribeClusters` | List clusters and their connection info |
| `UpdateCluster` | Update mutable cluster attributes (e.g. description) |
| `DeleteCluster` | Stop and remove a cluster |
+| `CreateUser` | - |
+| `DescribeUsers` | - |
+| `DeleteUser` | - |
+| `CreateACL` | - |
+| `DescribeACLs` | - |
+| `DeleteACL` | - |
| `ListTags` | List tags for a cluster |
| `TagResource` | Add tags to a cluster |
| `UntagResource` | Remove tags from a cluster |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/neptune.md b/docs/services/neptune.md
index 342487d05c..e1d4c0efc1 100644
--- a/docs/services/neptune.md
+++ b/docs/services/neptune.md
@@ -19,8 +19,9 @@ The proxy is a transparent byte relay, so the host-facing proxy port range is un
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|--------|-------------|
+| --- | --- |
| `CreateDBCluster` | Create a Neptune cluster and start a Gremlin Server container |
| `DescribeDBClusters` | List clusters and their connection details |
| `DeleteDBCluster` | Stop and remove a cluster |
@@ -29,6 +30,7 @@ The proxy is a transparent byte relay, so the host-facing proxy port range is un
| `DescribeDBInstances` | List instances |
| `DeleteDBInstance` | Remove an instance from a cluster |
| `ModifyDBInstance` | Update instance settings |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/rds.md b/docs/services/rds.md
index 754f88ed51..22f224838d 100644
--- a/docs/services/rds.md
+++ b/docs/services/rds.md
@@ -10,8 +10,9 @@ RDS Data API (`rds-data`) is documented separately because it uses REST JSON rou
## Supported Management Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateDBInstance` | Start a new database instance |
| `DescribeDBInstances` | List instances and their connection info |
| `DeleteDBInstance` | Stop and remove an instance |
@@ -22,9 +23,6 @@ RDS Data API (`rds-data`) is documented separately because it uses REST JSON rou
| `DescribeDBSubnetGroups` | List DB subnet groups |
| `ModifyDBSubnetGroup` | Update DB subnet group description and subnet list |
| `DeleteDBSubnetGroup` | Delete a DB subnet group |
-| `AddTagsToResource` | Add tags to a DB resource |
-| `ListTagsForResource` | List tags for a DB resource |
-| `RemoveTagsFromResource` | Remove tags from a DB resource |
| `CreateDBCluster` | Create an Aurora-compatible cluster |
| `DescribeDBClusters` | List clusters |
| `DeleteDBCluster` | Delete a cluster |
@@ -34,6 +32,15 @@ RDS Data API (`rds-data`) is documented separately because it uses REST JSON rou
| `DeleteDBParameterGroup` | Delete a parameter group |
| `ModifyDBParameterGroup` | Update parameter group settings |
| `DescribeDBParameters` | List parameters in a group |
+| `CreateDBClusterParameterGroup` | - |
+| `DescribeDBClusterParameterGroups` | - |
+| `DeleteDBClusterParameterGroup` | - |
+| `ModifyDBClusterParameterGroup` | - |
+| `DescribeDBClusterParameters` | - |
+| `AddTagsToResource` | Add tags to a DB resource |
+| `ListTagsForResource` | List tags for a DB resource |
+| `RemoveTagsFromResource` | Remove tags from a DB resource |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/secrets-manager.md b/docs/services/secrets-manager.md
index 85793707d1..9958de35a4 100644
--- a/docs/services/secrets-manager.md
+++ b/docs/services/secrets-manager.md
@@ -5,8 +5,9 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateSecret` | Create a new secret |
| `GetSecretValue` | Retrieve the current secret value |
| `PutSecretValue` | Update the secret value (new version) |
@@ -14,16 +15,18 @@
| `DescribeSecret` | Get secret metadata and version info |
| `ListSecrets` | List all secrets |
| `DeleteSecret` | Delete a secret (with recovery window) |
+| `RestoreSecret` | - |
| `RotateSecret` | Trigger secret rotation via a Lambda |
+| `TagResource` | Tag a secret |
+| `UntagResource` | Remove tags |
| `ListSecretVersionIds` | List all versions of a secret |
-| `UpdateSecretVersionStage` | Move a staging label between versions |
-| `BatchGetSecretValue` | Retrieve multiple secret values in one call |
-| `GetRandomPassword` | Generate a random password |
| `GetResourcePolicy` | Get the resource policy |
-| `PutResourcePolicy` | Attach a resource policy |
+| `GetRandomPassword` | Generate a random password |
+| `BatchGetSecretValue` | Retrieve multiple secret values in one call |
| `DeleteResourcePolicy` | Remove the resource policy |
-| `TagResource` | Tag a secret |
-| `UntagResource` | Remove tags |
+| `PutResourcePolicy` | Attach a resource policy |
+| `UpdateSecretVersionStage` | Move a staging label between versions |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/sqs.md b/docs/services/sqs.md
index f9b7996992..bcfe4f6eaa 100644
--- a/docs/services/sqs.md
+++ b/docs/services/sqs.md
@@ -5,28 +5,33 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateQueue` | Create a standard or FIFO queue |
| `DeleteQueue` | Delete a queue |
| `ListQueues` | List all queues |
| `GetQueueUrl` | Look up a queue URL by name |
| `GetQueueAttributes` | Get queue configuration attributes |
-| `SetQueueAttributes` | Update queue configuration |
| `SendMessage` | Send a message to a queue |
-| `SendMessageBatch` | Send up to 10 messages in one call |
| `ReceiveMessage` | Poll for messages |
| `DeleteMessage` | Acknowledge and delete a message |
| `DeleteMessageBatch` | Delete multiple messages at once |
+| `SendMessageBatch` | Send up to 10 messages in one call |
| `ChangeMessageVisibility` | Extend or reset a message's visibility timeout |
| `ChangeMessageVisibilityBatch` | Change visibility for multiple messages |
-| `PurgeQueue` | Delete all messages in a queue |
+| `SetQueueAttributes` | Update queue configuration |
| `TagQueue` | Add tags to a queue |
| `UntagQueue` | Remove tags from a queue |
| `ListQueueTags` | List tags on a queue |
+| `PurgeQueue` | Delete all messages in a queue |
| `ListDeadLetterSourceQueues` | Find queues that use this queue as DLQ |
| `StartMessageMoveTask` | Start a DLQ redrive task |
| `ListMessageMoveTasks` | List DLQ redrive tasks |
+| `CancelMessageMoveTask` | - |
+| `AddPermission` | - |
+| `RemovePermission` | - |
+<!-- floci:actions:end -->
## Local Inspection Endpoint
diff --git a/docs/services/step-functions.md b/docs/services/step-functions.md
index fdb8ab74f3..f773052c6e 100644
--- a/docs/services/step-functions.md
+++ b/docs/services/step-functions.md
@@ -5,14 +5,19 @@
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateStateMachine` | Create a state machine (Standard or Express) |
| `DescribeStateMachine` | Get state machine definition and metadata |
| `ListStateMachines` | List all state machines |
| `DeleteStateMachine` | Delete a state machine |
+| `PublishStateMachineVersion` | - |
+| `ListStateMachineVersions` | - |
+| `DeleteStateMachineVersion` | - |
| `ValidateStateMachineDefinition` | Validate an ASL definition without creating a state machine |
| `StartExecution` | Start a new execution |
+| `StartSyncExecution` | - |
| `DescribeExecution` | Get execution status and output |
| `ListExecutions` | List executions for a state machine |
| `StopExecution` | Stop a running execution |
@@ -20,6 +25,15 @@
| `SendTaskSuccess` | Report task success (for `.waitForTaskToken` tasks) |
| `SendTaskFailure` | Report task failure |
| `SendTaskHeartbeat` | Send a heartbeat for long-running tasks |
+| `CreateActivity` | - |
+| `DeleteActivity` | - |
+| `DescribeActivity` | - |
+| `ListActivities` | - |
+| `GetActivityTask` | - |
+| `ListTagsForResource` | - |
+| `TagResource` | - |
+| `UntagResource` | - |
+<!-- floci:actions:end -->
## Configuration
diff --git a/docs/services/wafv2.md b/docs/services/wafv2.md
index f3fa2cdcd0..44d6edf4ce 100644
--- a/docs/services/wafv2.md
+++ b/docs/services/wafv2.md
@@ -8,17 +8,14 @@ Floci emulates the AWS WAF v2 management API. Web ACLs, IP sets, regex pattern s
## Supported Actions
+<!-- floci:actions:start -->
| Action | Description |
-|---|---|
+| --- | --- |
| `CreateWebACL` | Creates a web ACL |
| `GetWebACL` | Returns a web ACL by name/id/scope |
| `UpdateWebACL` | Updates a web ACL (requires the current `LockToken`) |
| `DeleteWebACL` | Deletes a web ACL |
| `ListWebACLs` | Lists web ACLs for a scope |
-| `GetWebACLForResource` | Returns the web ACL associated with a resource |
-| `AssociateWebACL` | Associates a web ACL with a resource |
-| `DisassociateWebACL` | Removes a web ACL association from a resource |
-| `ListResourcesForWebACL` | Lists resources associated with a web ACL |
| `CreateIPSet` | Creates an IP set |
| `GetIPSet` | Returns an IP set |
| `UpdateIPSet` | Updates an IP set |
@@ -35,6 +32,10 @@ Floci emulates the AWS WAF v2 management API. Web ACLs, IP sets, regex pattern s
| `DeleteRuleGroup` | Deletes a rule group |
| `ListRuleGroups` | Lists rule groups for a scope |
| `CheckCapacity` | Returns the WCU capacity required for a set of rules |
+| `AssociateWebACL` | Associates a web ACL with a resource |
+| `DisassociateWebACL` | Removes a web ACL association from a resource |
+| `GetWebACLForResource` | Returns the web ACL associated with a resource |
+| `ListResourcesForWebACL` | Lists resources associated with a web ACL |
| `PutLoggingConfiguration` | Sets the logging configuration for a web ACL |
| `GetLoggingConfiguration` | Returns the logging configuration for a web ACL |
| `DeleteLoggingConfiguration` | Removes a logging configuration |
@@ -45,6 +46,7 @@ Floci emulates the AWS WAF v2 management API. Web ACLs, IP sets, regex pattern s
| `TagResource` | Adds tags to a WAF resource |
| `UntagResource` | Removes tags from a WAF resource |
| `ListTagsForResource` | Lists tags for a WAF resource |
+<!-- floci:actions:end -->
## Scope
diff --git a/tools/docs/regen_action_docs.py b/tools/docs/regen_action_docs.py
new file mode 100644
index 0000000000..055022eee4
--- /dev/null
+++ b/tools/docs/regen_action_docs.py
@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+"""Regenerate the action tables in docs/services/*.md from handler source.
+
+The action LIST is derived from handler source (never hand-edited, never drifts).
+The Description column is hand-written prose: regen PRESERVES existing descriptions
+keyed by action name and leaves a "-" placeholder for new/unknown actions. The
+generator only ever rewrites the bytes between the marker pair; everything else in
+the file is byte-identical pre and post.
+
+Assumption: a switch `case` label counts as supported purely by existing, so an arm
+that is present but throws `UnsupportedOperation` in its body would still be listed.
+Handlers here reject unsupported actions from the `default` arm, so this holds; a
+per-action stub that throws would be a false positive.
+
+Run from anywhere in the repo:
+ python3 tools/docs/regen_action_docs.py # rewrite docs in place
+ python3 tools/docs/regen_action_docs.py --strict # exit non-zero on warnings
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+MARKER_START = "<!-- floci:actions:start -->"
+MARKER_END = "<!-- floci:actions:end -->"
+
+PLACEHOLDER = "-"
+
+# `case "ActionName" ->` switch arms (Query / JSON 1.1 protocols). A single arm may
+# carry several labels: `case "Foo", "Bar", "Baz" ->`; all are extracted, in order.
+# The label list may also wrap across lines (valid Java 14+ switch syntax), so the
+# capture group excludes only the `{ } ;` statement/body boundaries rather than
+# newlines: it spans line breaks between labels but stops at the arm's `->` and can't
+# run into an arm body or a colon-style `case` that has no `->`. Without this a
+# wrapped arm would be silently dropped, and `docs-check` would stay green because the
+# doc and the tool's output would agree on the omission.
+# The label head requires `[A-Z][a-z]` (PascalCase), which deliberately excludes
+# SCREAMING_CASE enum labels in non-action switches a handler may also contain
+# (e.g. `switch (state) { case "DISABLED" -> ... }`). AWS action names are always
+# PascalCase, so no real action is lost.
+SWITCH_CASE_RE = re.compile(r"^\s*case\s+([^{};]+?)\s*->", re.MULTILINE)
+SWITCH_LABEL_RE = re.compile(r'"([A-Z][a-z][A-Za-z0-9]*)"')
+
+# REST controllers: a JAX-RS verb annotation followed by the public method it decorates,
+# inside a class that carries a class-level @Path. The action is ucfirst(methodName),
+# corrected per-service via rename_actions / exclude_actions (method names are not
+# always the canonical AWS action, e.g. updateV2Integration -> UpdateIntegration).
+CLASS_PATH_RE = re.compile(r"^\s*@Path\b", re.MULTILINE)
+HTTP_ANNO_RE = re.compile(r"^\s*@(?:GET|POST|PUT|DELETE|PATCH)\b")
+ANNOTATION_LINE_RE = re.compile(r"^\s*@\w")
+PUBLIC_METHOD_RE = re.compile(r"^\s*public\s+\S+(?:<[^>]*>)?\s+([a-z][A-Za-z0-9]*)\s*\(")
+# Line/block-comment lines (Javadoc) that may sit between the verb annotation and the
+# method signature; skipped so they don't reset the `pending` flag mid-lookahead.
+COMMENT_LINE_RE = re.compile(r"^\s*(?://|/\*|\*)")
+
+
+@dataclass(frozen=True)
+class Source:
+ path: Path
+ mode: str # 'switch' | 'rest'
+
+
+@dataclass(frozen=True)
+class ServiceEntry:
+ service: str
+ doc: Path
+ sources: list[Source]
+ rename_actions: dict[str, str] = field(default_factory=dict)
+ exclude_actions: frozenset[str] = field(default_factory=frozenset)
+ handler: Path | None = None # optional explicit handler path for excluded services
+
+
+# --------------------------------------------------------------------------- #
+# Extraction (pure functions over Java source text)
+# --------------------------------------------------------------------------- #
+def extract_switch_actions(java_source: str) -> list[str]:
+ """Action names from `case "X" ->` arms, in source order.
+
+ Handles multi-label arms (`case "A", "B" ->`) by extracting every quoted
+ PascalCase label up to the arm's `->`.
+ """
+ out: list[str] = []
+ for arm in SWITCH_CASE_RE.finditer(java_source):
+ out.extend(m.group(1) for m in SWITCH_LABEL_RE.finditer(arm.group(1)))
+ return out
+
+
+def extract_rest_actions(java_source: str) -> list[str]:
+ """ucfirst(method name) of @GET/@POST/@PUT/@DELETE/@PATCH methods, source order.
+
+ Only applies to classes containing a class-level @Path. Returns [] otherwise.
+ """
+ if not CLASS_PATH_RE.search(java_source):
+ return []
+ actions: list[str] = []
+ pending = False
+ for line in java_source.splitlines():
+ if not line.strip():
+ continue
+ if HTTP_ANNO_RE.match(line):
+ pending = True
+ continue
+ if not pending:
+ continue
+ if ANNOTATION_LINE_RE.match(line):
+ continue
+ if COMMENT_LINE_RE.match(line):
+ continue
+ m = PUBLIC_METHOD_RE.match(line)
+ if m:
+ name = m.group(1)
+ actions.append(name[0].upper() + name[1:])
+ pending = False
+ return actions
+
+
+def extract_actions(entry: ServiceEntry) -> list[str]:
+ """Merged, deduped, override-corrected action list for a service.
+
+ Order: first appearance across the source list in registry order. rename_actions
+ is applied before dedup (so a renamed collision dedupes correctly); excluded
+ names are dropped after rename.
+ """
+ seen: set[str] = set()
+ out: list[str] = []
+ for source in entry.sources:
+ text = source.path.read_text(encoding="utf-8")
+ if source.mode == "switch":
+ raw = extract_switch_actions(text)
+ elif source.mode == "rest":
+ raw = extract_rest_actions(text)
+ else:
+ raise ValueError(f"unknown mode: {source.mode!r}")
+ for name in raw:
+ name = entry.rename_actions.get(name, name)
+ if name in entry.exclude_actions:
+ continue
+ if name not in seen:
+ seen.add(name)
+ out.append(name)
+ return out
+
+
+# --------------------------------------------------------------------------- #
+# Markdown marker block: parse existing descriptions, render new table
+# --------------------------------------------------------------------------- #
+_SEPARATOR_ROW_RE = re.compile(r"^\|[\s:|-]+\|$")
+
+
+def _split_row(row: str) -> list[str]:
+ """Split a markdown table row into trimmed cells, honoring escaped pipes (\\|).
+
+ A literal pipe inside a cell must be written as \\| in markdown; an unescaped |
+ is always a column separator (including pipes inside inline code, which is why
+ descriptions should escape them). The split is on unescaped pipes only.
+ """
+ cells: list[str] = []
+ buf: list[str] = []
+ i = 0
+ n = len(row)
+ while i < n:
+ ch = row[i]
+ if ch == "\\" and i + 1 < n and row[i + 1] == "|":
+ buf.append("|")
+ i += 2
+ continue
+ if ch == "|":
+ cells.append("".join(buf).strip())
+ buf = []
+ i += 1
+ continue
+ buf.append(ch)
+ i += 1
+ cells.append("".join(buf).strip())
+ # A well-formed row starts and ends with |, producing empty edge cells; drop them.
+ if cells and cells[0] == "":
+ cells = cells[1:]
+ if cells and cells[-1] == "":
+ cells = cells[:-1]
+ return cells
+
+
+def _strip_action_cell(cell: str) -> str:
+ """Normalize an action cell to the bare action name (handles `Backticked` form)."""
+ return cell.strip().strip("`").strip()
+
+
+def parse_marker_block(md: str) -> tuple[str, dict[str, str], str]:
+ """Split a doc around the marker block.
+
+ Returns (prefix_through_start_marker_line, {action: description}, suffix_from_end_marker_line).
+ Raises ValueError if markers are missing, unbalanced, or the enclosed table is malformed.
+ """
+ if md.count(MARKER_START) != 1 or md.count(MARKER_END) != 1:
+ raise ValueError(
+ f"document must contain exactly one '{MARKER_START}' and one '{MARKER_END}'"
+ )
+ start_idx = md.index(MARKER_START)
+ end_idx = md.index(MARKER_END)
+ if end_idx < start_idx:
+ raise ValueError("end marker appears before start marker")
+
+ try:
+ after_start = md.index("\n", start_idx) + 1
+ before_end = md.rindex("\n", 0, end_idx) + 1
+ except ValueError:
+ raise ValueError(
+ f"'{MARKER_START}' and '{MARKER_END}' must each sit on their own line"
+ ) from None
+
+ prefix = md[:after_start]
+ suffix = md[before_end:]
+ body = md[after_start:before_end]
+ return prefix, _parse_table(body), suffix
+
+
+def _parse_table(body: str) -> dict[str, str]:
+ """Parse {action: description} from the table inside the marker block.
+
+ Tolerant of a missing/extra Description column, padded alignment rows, and an
+ empty block (first migration). Rejects rows that don't look like a table row
+ once a table has started, loudly, rather than silently dropping content.
+ """
+ descriptions: dict[str, str] = {}
+ seen_header = False
+ for line in body.splitlines():
+ stripped = line.strip()
+ if not stripped:
+ continue
+ if not stripped.startswith("|"):
+ raise ValueError(f"unexpected non-table line inside marker block: {stripped!r}")
+ if _SEPARATOR_ROW_RE.match(stripped):
+ continue
+ cells = _split_row(stripped)
+ if not cells:
+ continue
+ if len(cells) > 2:
+ raise ValueError(
+ f"malformed table row, expected at most 2 columns "
+ f"(escape literal pipes as '\\|'): {stripped!r}"
+ )
+ action = _strip_action_cell(cells[0])
+ # Skip the header row (its first cell is the literal "Action").
+ if not seen_header and action.lower() == "action":
+ seen_header = True
+ continue
+ seen_header = True
+ if not action:
+ continue
+ desc = cells[1].strip() if len(cells) > 1 else ""
+ if desc == PLACEHOLDER:
+ desc = ""
+ descriptions[action] = desc
+ return descriptions
+
+
+def render_marker_block(actions: list[str], descriptions: dict[str, str]) -> str:
+ """Render the table that goes between the marker lines (two columns).
+
+ Preserves a known description; emits the "-" placeholder for an unknown action.
+ """
+ lines = ["| Action | Description |", "| --- | --- |"]
+ for action in actions:
+ desc = descriptions.get(action) or PLACEHOLDER
+ # Descriptions are held unescaped in memory; re-escape literal pipes so the
+ # cell round-trips through _split_row on the next regen instead of splitting.
+ desc = desc.replace("|", r"\|")
+ lines.append(f"| `{action}` | {desc} |")
+ return "\n".join(lines) + "\n"
+
+
+def regenerate_doc_content(
+ actions: list[str], doc_content: str
+) -> tuple[str, list[str]]:
+ """Pure: given the new action list and the current doc, return (new_doc, orphans).
+
+ Orphans are actions present in the doc's old block but no longer in source; their
+ descriptions are dropped from the new block (the row goes away).
+ """
+ prefix, prior, suffix = parse_marker_block(doc_content)
+ keep = set(actions)
+ orphans = [a for a in prior if a not in keep]
+ body = render_marker_block(actions, prior)
+ return prefix + body + suffix, orphans
+
+
+# --------------------------------------------------------------------------- #
+# Registry + driver
+# --------------------------------------------------------------------------- #
+def _repo_root() -> Path:
+ return Path(__file__).resolve().parent.parent.parent
+
+
+def _load_registry(repo_root: Path) -> tuple[list[ServiceEntry], set[Path]]:
+ """Load services.yaml. Returns (service entries, acknowledged deferred handler paths).
+
+ Schema: a top-level mapping with `services:` (the registered entries) and
+ `deferred_handlers:` (switch handlers known to exist but intentionally not yet
+ covered, so the unregistered-handler sentinel doesn't flag them every run).
+ """
+ registry_path = repo_root / "tools" / "docs" / "services.yaml"
+ raw = yaml.safe_load(registry_path.read_text(encoding="utf-8")) or {}
+ entries: list[ServiceEntry] = []
+ for item in raw.get("services") or []:
+ sources = [
+ Source(path=repo_root / s["path"], mode=s["mode"])
+ for s in item.get("sources") or []
+ ]
+ handler = item.get("handler")
+ entries.append(
+ ServiceEntry(
+ service=item["service"],
+ doc=repo_root / item["doc"],
+ sources=sources,
+ rename_actions=dict(item.get("rename_actions") or {}),
+ exclude_actions=frozenset(item.get("exclude_actions") or []),
+ handler=repo_root / handler if handler else None,
+ )
+ )
+ deferred = {
+ (repo_root / d["path"]).resolve()
+ for d in raw.get("deferred_handlers") or []
+ }
+ return entries, deferred
+
+
+def _process_entry(entry: ServiceEntry) -> tuple[bool, list[str]]:
+ """Regenerate one service's doc. Returns (changed, orphans). Skip-mode is a no-op."""
+ if not entry.sources:
+ return False, []
+ actions = extract_actions(entry)
+ doc_content = entry.doc.read_text(encoding="utf-8")
+ new_content, orphans = regenerate_doc_content(actions, doc_content)
+ if new_content != doc_content:
+ entry.doc.write_text(new_content, encoding="utf-8")
+ return True, orphans
+ return False, orphans
+
+
+def _find_unregistered_handlers(
+ repo_root: Path, entries: list[ServiceEntry], deferred: set[Path]
+) -> list[str]:
+ """Top-level *Handler.java files that produce switch actions but aren't registered
+ and aren't on the deferred allowlist.
+
+ New-service drift sentinel: a brand-new switch handler must be either registered
+ or added to deferred_handlers (with a reason), or this fails --strict. REST
+ controllers are opt-in (per-judgment) and not flagged here.
+ """
+ services_root = repo_root / "src/main/java/io/github/hectorvent/floci/services"
+ registered = {s.path.resolve() for entry in entries for s in entry.sources}
+ registered |= {entry.handler.resolve() for entry in entries if entry.handler}
+ registered |= deferred
+ unregistered: list[str] = []
+ # Recursive: handlers live at varying depths (e.g. cloudwatch/logs/, cloudwatch/metrics/).
+ for path in sorted(services_root.glob("**/[A-Z]*Handler.java")):
+ if path.resolve() in registered:
+ continue
+ if not extract_switch_actions(path.read_text(encoding="utf-8")):
+ continue
+ unregistered.append(str(path.relative_to(repo_root)))
+ return unregistered
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--strict",
+ action="store_true",
+ help="treat warnings (orphan actions, unregistered handlers) as errors",
+ )
+ args = parser.parse_args(argv)
+
+ repo_root = _repo_root()
+ entries, deferred = _load_registry(repo_root)
+
+ warnings: list[str] = []
+ for entry in entries:
+ try:
+ changed, orphans = _process_entry(entry)
+ except (ValueError, FileNotFoundError) as exc:
+ print(f"error: {entry.service}: {exc}", file=sys.stderr)
+ return 1
+ if changed:
+ print(f"updated {entry.doc.relative_to(repo_root)}")
+ for orphan in orphans:
+ warnings.append(
+ f"{entry.service}: action '{orphan}' was in the doc but not in source (row dropped)"
+ )
+
+ for handler in _find_unregistered_handlers(repo_root, entries, deferred):
+ warnings.append(
+ f"unregistered handler '{handler}' produces actions but is not in "
+ f"tools/docs/services.yaml (register it or add to deferred_handlers)"
+ )
+
+ for w in warnings:
+ print(f"warning: {w}", file=sys.stderr)
+
+ if args.strict and warnings:
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/docs/requirements.txt b/tools/docs/requirements.txt
new file mode 100644
index 0000000000..26efb36e3a
--- /dev/null
+++ b/tools/docs/requirements.txt
@@ -0,0 +1,2 @@
+PyYAML>=6.0
+pytest>=7.0
diff --git a/tools/docs/services.yaml b/tools/docs/services.yaml
new file mode 100644
index 0000000000..debcbb0d9c
--- /dev/null
+++ b/tools/docs/services.yaml
@@ -0,0 +1,123 @@
+# Registry of services whose Supported Actions tables are auto-generated.
+#
+# The action LIST comes from handler source (mode: switch|rest); the Description
+# column is hand-written and PRESERVED across regen, keyed by action name.
+# Per-service overrides: rename_actions (method->canonical), exclude_actions.
+#
+# Phase 1 covers single-table switch-mode services. REST controllers, multi-table
+# docs, mixed-mode (ses), S3 query-string dispatch, and non-tabular docs are tracked
+# as follow-ups; their switch handlers are acknowledged in deferred_handlers below so
+# the new-service sentinel only fires on genuinely unregistered handlers.
+
+services:
+ - service: acm
+ doc: docs/services/acm.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/acm/AcmJsonHandler.java, mode: switch }
+ - service: athena
+ doc: docs/services/athena.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/athena/AthenaJsonHandler.java, mode: switch }
+ - service: cloudformation
+ doc: docs/services/cloudformation.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudformation/CloudFormationQueryHandler.java, mode: switch }
+ - service: cloudtrail
+ doc: docs/services/cloudtrail.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudtrail/CloudTrailJsonHandler.java, mode: switch }
+ - service: docdb
+ doc: docs/services/docdb.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/docdb/DocDbQueryHandler.java, mode: switch }
+ - service: elasticache
+ doc: docs/services/elasticache.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/elasticache/ElastiCacheQueryHandler.java, mode: switch }
+ - service: emr
+ doc: docs/services/emr.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/emr/EmrHandler.java, mode: switch }
+ - service: eventbridge
+ doc: docs/services/eventbridge.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/eventbridge/EventBridgeHandler.java, mode: switch }
+ - service: firehose
+ doc: docs/services/firehose.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/firehose/FirehoseJsonHandler.java, mode: switch }
+ - service: kinesis
+ doc: docs/services/kinesis.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/kinesis/KinesisJsonHandler.java, mode: switch }
+ - service: kms
+ doc: docs/services/kms.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/kms/KmsJsonHandler.java, mode: switch }
+ - service: memorydb
+ doc: docs/services/memorydb.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/memorydb/MemoryDbHandler.java, mode: switch }
+ - service: neptune
+ doc: docs/services/neptune.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/neptune/NeptuneQueryHandler.java, mode: switch }
+ - service: rds
+ doc: docs/services/rds.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/rds/RdsQueryHandler.java, mode: switch }
+ - service: secretsmanager
+ doc: docs/services/secrets-manager.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/secretsmanager/SecretsManagerJsonHandler.java, mode: switch }
+ - service: sqs
+ doc: docs/services/sqs.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/sqs/SqsJsonHandler.java, mode: switch }
+ - { path: src/main/java/io/github/hectorvent/floci/services/sqs/SqsQueryHandler.java, mode: switch }
+ - service: stepfunctions
+ doc: docs/services/step-functions.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonHandler.java, mode: switch }
+ - service: wafv2
+ doc: docs/services/wafv2.md
+ sources:
+ - { path: src/main/java/io/github/hectorvent/floci/services/wafv2/WafV2Handler.java, mode: switch }
+
+# Switch handlers that exist but are intentionally not yet covered (see reasons).
+# A NEW switch handler not listed here and not registered above fails `--strict`.
+deferred_handlers:
+ - { path: src/main/java/io/github/hectorvent/floci/services/apigatewayv2/ApiGatewayV2JsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/autoscaling/AutoScalingQueryHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/bcmdataexports/BcmDataExportsJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/ce/CostExplorerJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudcontrol/CloudControlJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudmap/CloudMapHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudwatch/logs/CloudWatchLogsHandler.java } # multi-table doc (nested handler)
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudwatch/metrics/CloudWatchMetricsJsonHandler.java } # multi-table doc (nested handler)
+ - { path: src/main/java/io/github/hectorvent/floci/services/cloudwatch/metrics/CloudWatchMetricsQueryHandler.java } # multi-table doc (nested handler)
+ - { path: src/main/java/io/github/hectorvent/floci/services/codebuild/CodeBuildJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/codedeploy/CodeDeployJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/cognito/CognitoJsonHandler.java } # non-tabular doc (grouped/inline); separate docs effort
+ - { path: src/main/java/io/github/hectorvent/floci/services/configservice/ConfigServiceJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/cur/CurJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/dynamodb/DynamoDbJsonHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/dynamodb/DynamoDbStreamsJsonHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/ec2/Ec2QueryHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/ecr/EcrJsonHandler.java } # doc packs multiple actions per row (`A` / `B`) + REST endpoints; needs de-grouping
+ - { path: src/main/java/io/github/hectorvent/floci/services/ecs/EcsJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/elasticbeanstalk/ElasticBeanstalkQueryHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/elbv2/ElbV2QueryHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/glue/GlueJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/iam/IamQueryHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/iam/StsQueryHandler.java } # sts (lives in iam package); single-table, registerable next
+ - { path: src/main/java/io/github/hectorvent/floci/services/pricing/PricingJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/resourcegroupstagging/ResourceGroupsTaggingJsonHandler.java } # non-tabular doc (grouped/inline)
+ - { path: src/main/java/io/github/hectorvent/floci/services/ses/SesQueryHandler.java } # mixed-mode (Query + REST surface)
+ - { path: src/main/java/io/github/hectorvent/floci/services/sns/SnsJsonHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/sns/SnsQueryHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/ssm/Ec2MessagesJsonHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/ssm/SsmJsonHandler.java } # multi-table doc
+ - { path: src/main/java/io/github/hectorvent/floci/services/textract/TextractJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/transcribe/TranscribeJsonHandler.java } # no standalone action table yet
+ - { path: src/main/java/io/github/hectorvent/floci/services/transfer/TransferHandler.java } # multi-table doc
diff --git a/tools/docs/test_regen_action_docs.py b/tools/docs/test_regen_action_docs.py
new file mode 100644
index 0000000000..11540830b5
--- /dev/null
+++ b/tools/docs/test_regen_action_docs.py
@@ -0,0 +1,251 @@
+"""Tests for regen_action_docs.
+
+Run with: pytest tools/docs -q (or: make docs-test)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import regen_action_docs as r
+
+
+# --------------------------------------------------------------------------- #
+# Extraction: switch
+# --------------------------------------------------------------------------- #
+def test_extract_switch_single_label():
+ src = """
+ return switch (action) {
+ case "CreateSecret" -> handleCreate(req);
+ case "GetSecretValue" -> handleGet(req);
+ default -> error();
+ };
+ """
+ assert r.extract_switch_actions(src) == ["CreateSecret", "GetSecretValue"]
+
+
+def test_extract_switch_multi_label_arm():
+ # A single arm carrying several labels (real case: CloudFormation StackSets).
+ src = 'case "ListStackSets", "DescribeStackSet", "CreateStackSet" -> handleStackSets(req);'
+ assert r.extract_switch_actions(src) == [
+ "ListStackSets",
+ "DescribeStackSet",
+ "CreateStackSet",
+ ]
+
+
+def test_extract_switch_multiline_arm():
+ # Labels wrapped across lines (valid Java 14+ switch syntax) must all be captured,
+ # and the capture must stop at the arm's `->` rather than running into the next
+ # arm's `{ ... }` body. A miss here would be invisible: the doc and the regenerated
+ # output would agree on the omission and docs-check would stay green.
+ src = '''
+ return switch (action) {
+ case "CreateStackSet",
+ "DescribeStackSet",
+ "ListStackSets" -> handleStackSets(req);
+ case "GetTemplate" -> { return handleGet(req); }
+ };
+ '''
+ assert r.extract_switch_actions(src) == [
+ "CreateStackSet",
+ "DescribeStackSet",
+ "ListStackSets",
+ "GetTemplate",
+ ]
+
+
+def test_extract_switch_ignores_non_pascal_and_default():
+ src = '''
+ case "lowercase" -> a();
+ case null, default -> b();
+ case "Good" -> c();
+ '''
+ assert r.extract_switch_actions(src) == ["Good"]
+
+
+def test_extract_switch_excludes_screaming_case_enum_labels():
+ # A handler may contain non-action switches (e.g. state enums). SCREAMING_CASE
+ # labels must not be picked up as actions; PascalCase actions still are.
+ src = '''
+ return switch (action) {
+ case "EnableRule" -> enable();
+ case "DisableRule" -> disable();
+ };
+ return switch (state.toUpperCase()) {
+ case "DISABLED" -> RuleState.DISABLED;
+ case "ENABLED" -> RuleState.ENABLED;
+ };
+ '''
+ assert r.extract_switch_actions(src) == ["EnableRule", "DisableRule"]
+
+
+# --------------------------------------------------------------------------- #
+# Extraction: rest + overrides
+# --------------------------------------------------------------------------- #
+REST_CONTROLLER = """
+@Path("/")
+public class ThingController {
+ @POST
+ public Response createThing(Req r) { return ok(); }
+
+ @GET
+ public Response listThingsPost(Req r) { return ok(); }
+
+ @PUT
+ public Response updateV2Thing(Req r) { return ok(); }
+}
+"""
+
+
+def test_extract_rest_ucfirsts_method_names():
+ assert r.extract_rest_actions(REST_CONTROLLER) == [
+ "CreateThing",
+ "ListThingsPost",
+ "UpdateV2Thing",
+ ]
+
+
+def test_extract_rest_requires_class_path():
+ no_path = REST_CONTROLLER.replace('@Path("/")\n', "")
+ assert r.extract_rest_actions(no_path) == []
+
+
+def test_extract_rest_skips_comments_between_annotation_and_method():
+ # A Javadoc or inline comment sitting between the verb annotation and the method
+ # signature must not reset the lookahead and drop the action.
+ src = '''
+@Path("/")
+public class C {
+ @POST
+ /** Creates a thing. */
+ public Response createThing(Req r) { return ok(); }
+
+ @GET
+ // list them
+ public Response listThings(Req r) { return ok(); }
+}
+'''
+ assert r.extract_rest_actions(src) == ["CreateThing", "ListThings"]
+
+
+def test_extract_actions_applies_rename_and_exclude(tmp_path: Path):
+ src = tmp_path / "ThingController.java"
+ src.write_text(REST_CONTROLLER)
+ entry = r.ServiceEntry(
+ service="thing",
+ doc=tmp_path / "thing.md",
+ sources=[r.Source(path=src, mode="rest")],
+ rename_actions={"UpdateV2Thing": "UpdateThing"},
+ exclude_actions=frozenset({"ListThingsPost"}),
+ )
+ assert r.extract_actions(entry) == ["CreateThing", "UpdateThing"]
+
+
+def test_extract_actions_dedupes_across_sources(tmp_path: Path):
+ a = tmp_path / "A.java"
+ b = tmp_path / "B.java"
+ a.write_text('case "Foo" -> x();\ncase "Bar" -> y();')
+ b.write_text('case "Bar" -> y();\ncase "Baz" -> z();')
+ entry = r.ServiceEntry(
+ service="s",
+ doc=tmp_path / "s.md",
+ sources=[r.Source(path=a, mode="switch"), r.Source(path=b, mode="switch")],
+ )
+ assert r.extract_actions(entry) == ["Foo", "Bar", "Baz"]
+
+
+# --------------------------------------------------------------------------- #
+# Table parsing: robustness
+# --------------------------------------------------------------------------- #
+def test_split_row_honors_escaped_pipe():
+ assert r._split_row(r"| `Foo` | a \| b |") == ["`Foo`", "a | b"]
+
+
+def test_parse_marker_block_preserves_descriptions():
+ md = (
+ "pre\n"
+ f"{r.MARKER_START}\n"
+ "| Action | Description |\n"
+ "| --- | --- |\n"
+ "| `CreateSecret` | Create a new secret |\n"
+ "| `GetSecretValue` | - |\n"
+ f"{r.MARKER_END}\n"
+ "post\n"
+ )
+ _, descs, _ = r.parse_marker_block(md)
+ assert descs == {"CreateSecret": "Create a new secret", "GetSecretValue": ""}
+
+
+def test_parse_marker_block_rejects_missing_markers():
+ with pytest.raises(ValueError):
+ r.parse_marker_block("no markers here")
+
+
+def test_parse_table_rejects_non_table_line():
+ body = "| Action | Description |\n| --- | --- |\nstray prose line\n"
+ with pytest.raises(ValueError):
+ r._parse_table(body)
+
+
+def test_parse_table_rejects_extra_columns():
+ # An unescaped pipe in a hand-edited description yields a 3-cell row; reject it
+ # loudly rather than silently dropping the trailing text.
+ body = "| Action | Description |\n| --- | --- |\n| `Foo` | a | b |\n"
+ with pytest.raises(ValueError):
+ r._parse_table(body)
+
+
+def test_pipe_in_description_round_trips():
+ # A description containing a literal pipe survives render -> parse -> render
+ # unchanged (render escapes, the parser unescapes), and stays idempotent.
+ block = r.render_marker_block(["Foo"], {"Foo": "does a | b"})
+ assert r"\|" in block # escaped on render
+ md = f"x\n{r.MARKER_START}\n{block}{r.MARKER_END}\n"
+ _, descs, _ = r.parse_marker_block(md)
+ assert descs["Foo"] == "does a | b" # unescaped on parse
+ assert r.render_marker_block(["Foo"], descs) == block # idempotent
+
+
+# --------------------------------------------------------------------------- #
+# Regeneration: preservation, placeholders, orphans, idempotency
+# --------------------------------------------------------------------------- #
+DOC = (
+ "# Svc\n\n## Supported Actions\n\n"
+ f"{r.MARKER_START}\n"
+ "| Action | Description |\n"
+ "| --- | --- |\n"
+ "| `CreateSecret` | Create a new secret |\n"
+ "| `OldAction` | gone from code |\n"
+ f"{r.MARKER_END}\n\n## Configuration\nprose\n"
+)
+
+
+def test_regenerate_preserves_known_and_placeholders_new():
+ actions = ["CreateSecret", "GetSecretValue"]
+ new, orphans = r.regenerate_doc_content(actions, DOC)
+ _, descs, _ = r.parse_marker_block(new)
+ assert descs["CreateSecret"] == "Create a new secret" # preserved
+ assert descs["GetSecretValue"] == "" # new -> placeholder
+ assert orphans == ["OldAction"] # dropped + reported
+ assert "OldAction" not in new
+
+
+def test_regenerate_is_idempotent():
+ actions = ["CreateSecret", "GetSecretValue"]
+ once, _ = r.regenerate_doc_content(actions, DOC)
+ twice, _ = r.regenerate_doc_content(actions, once)
+ assert once == twice
+
+
+def test_regenerate_touches_only_marker_block():
+ actions = ["CreateSecret", "GetSecretValue"]
+ new, _ = r.regenerate_doc_content(actions, DOC)
+ assert new.split(r.MARKER_START)[0] == DOC.split(r.MARKER_START)[0]
+ assert new.split(r.MARKER_END)[1] == DOC.split(r.MARKER_END)[1]
+
+
+def test_render_marker_block_shape():
+ out = r.render_marker_block(["Foo"], {"Foo": "does foo"})
+ assert out == "| Action | Description |\n| --- | --- |\n| `Foo` | does foo |\n"