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.ymlnew file mode 100644index 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-checkdiff --git a/.gitignore b/.gitignoreindex 7a859fd4b6..47347747eb 100644--- a/.gitignore+++ b/.gitignore@@ -32,3 +32,7 @@ test-results.xmltest-resultsscripts/node_modules/++# Python tooling caches+__pycache__/+*.pycdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1560ff4421..02f7a3bcee 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -212,6 +212,25 @@ Maintainers may request additional or more targeted test coverage before approviCI 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 IssuesPlease 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/Makefilenew file mode 100644index 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 -qdiff --git a/docs/services/acm.md b/docs/services/acm.mdindex 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 Behaviordiff --git a/docs/services/athena.md b/docs/services/athena.mdindex 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 worksdiff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.mdindex 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 Typesdiff --git a/docs/services/cloudtrail.md b/docs/services/cloudtrail.mdindex 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 -->## Examplediff --git a/docs/services/docdb.md b/docs/services/docdb.mdindex 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 -->## Configurationdiff --git a/docs/services/elasticache.md b/docs/services/elasticache.mdindex 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 -->## Configurationdiff --git a/docs/services/emr.md b/docs/services/emr.mdindex 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 -->## Examplediff --git a/docs/services/eventbridge.md b/docs/services/eventbridge.mdindex 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 -->## Configurationdiff --git a/docs/services/firehose.md b/docs/services/firehose.mdindex 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 worksdiff --git a/docs/services/kinesis.md b/docs/services/kinesis.mdindex 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 Addressingdiff --git a/docs/services/kms.md b/docs/services/kms.mdindex 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 Scopediff --git a/docs/services/memorydb.md b/docs/services/memorydb.mdindex 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 -->## Configurationdiff --git a/docs/services/neptune.md b/docs/services/neptune.mdindex 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 -->## Configurationdiff --git a/docs/services/rds.md b/docs/services/rds.mdindex 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 -->## Configurationdiff --git a/docs/services/secrets-manager.md b/docs/services/secrets-manager.mdindex 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 -->## Configurationdiff --git a/docs/services/sqs.md b/docs/services/sqs.mdindex 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 Endpointdiff --git a/docs/services/step-functions.md b/docs/services/step-functions.mdindex 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 -->## Configurationdiff --git a/docs/services/wafv2.md b/docs/services/wafv2.mdindex 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 -->## Scopediff --git a/tools/docs/regen_action_docs.py b/tools/docs/regen_action_docs.pynew file mode 100644index 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.txtnew file mode 100644index 0000000000..26efb36e3a--- /dev/null+++ b/tools/docs/requirements.txt@@ -0,0 +1,2 @@+PyYAML>=6.0+pytest>=7.0diff --git a/tools/docs/services.yaml b/tools/docs/services.yamlnew file mode 100644index 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 docdiff --git a/tools/docs/test_regen_action_docs.py b/tools/docs/test_regen_action_docs.pynew file mode 100644index 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"