Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (48 loc) · 5.99 KB

AGENTS.md

File metadata and controls

64 lines (48 loc) · 5.99 KB

AI Agent Instructions for LocalStack AWS Proxy Extension

This repo is a LocalStack extension (plugin) that enables a "proxy mode" - proxying requests for certain AWS services (e.g., S3) to the upstream real AWS cloud, while handling the remaining services locally.

You are an AI agent tasked with adding additional functionality or test coverage to this repo.

General Instructions

  • You can assume that the LocalStack container is running locally, with the proxy extension installed and enabled.
  • You can assume that test AWS credentials are configured in the shell environment where the AI agent is running.
  • Do not touch any files outside the working directory (basedir of this file)!
  • You can create new files (no need to prompt for confirmation)
  • You can make modifications to files (no need to prompt for confirmation)
  • You can delete existing files if needed, but only after user confirmation
  • You can call different make targets (e.g., make test) in this repo (no need to prompt for confirmation)
  • For each new file created or existing file modified, add a header comment to the file, something like # Note: This file has been (partially or fully) generated by an AI agent.
  • The proxy tests are executed against real AWS and may incur some costs, so rather than executing the entire test suite or entire modules, focus the testing on individual test functions within a module only.
  • Before claiming success, always double-check against real AWS (via aws CLI commands) that everything has been cleaned up and there are no leftover resources from the proxy tests.
  • Never add any print(..) statements to the code - use a logger to report any status to the user, if required.
  • To format/lint the codebase you can run make format and make lint.

Testing

The proxy functionality is covered by integration tests in the tests/ folder, one file for each different AWS service (e.g., SQS, S3, etc).

To add a test, follow the pattern in the existing tests. It usually involves creating two boto3 clients, one for the LocalStack connection, and one for the real upstream AWS cloud. We then run API requests with both clients and assert that the results are identical, thereby ensuring that the proxy functionality is working properly.

To run a single test via pytest (say, test_my_logic in test_s3.py), use the following command:

TEST_PATH=tests/test_s3.py::test_my_logic make test

Read-Only Mode Support

Some services have operations that are functionally read-only (don't modify state) but don't follow the standard naming conventions (Describe*, Get*, List*, Query*). When adding tests or support for a new service with read_only: true configuration, check the AWS Service Authorization Reference for the service and identify any operations that:

  • Are classified as "Read" access level but don't match the standard prefixes
  • Evaluate or simulate something without modifying state (e.g., Evaluate*, Simulate*, Test*, Check*, Validate*)

If you find such operations, add them to the service-specific rules in aws_proxy/server/aws_request_forwarder.py in the _is_read_request method. This ensures that read-only proxy configurations correctly forward these operations rather than blocking them.

IMPORTANT: This step is mandatory when adding a new service. Failure to identify non-standard read-only operations will cause read_only: true configurations to incorrectly block legitimate read requests.

Example services with non-standard read-only operations:

  • AppSync: EvaluateCode, EvaluateMappingTemplate
  • IAM: SimulateCustomPolicy, SimulatePrincipalPolicy
  • Cognito: InitiateAuth
  • DynamoDB: Scan, BatchGetItem, PartiQLSelect

When adding new integration tests, consider the following:

  • Include a mix of positive and negative assertions (i.e., presence and absence of resources).
  • Include a mix of different configuration options, e.g., the read_only: true flag can be specified in the proxy service configuration YAML, enabling read-only mode (which should be covered by tests as well).
  • Include some tests that cover matching of resource names (the config YAML allows to specify ARN regex patterns), to ensure the proxy is able to selectively forward requests to certain matching AWS resources only.
  • Make sure to either use fixtures (preferred), or reliable cleanups for removing the resources; several fixtures for creating AWS resources are available in the localstack.testing.pytest.fixtures module
  • If a test uses multiple resources with interdependencies (e.g., an SQS queue connected to an SNS topic), then the test needs to ensure that both resource types are proxied (i.e., created in real AWS), to avoid a situation where a resource in AWS is attempting to reference a local resource in LocalStack (using account ID 000000000000 in their ARN).
  • When waiting for the creation status of a resource, use the localstack.utils.sync.retry(..) utility function, rather than a manual for loop.
  • Avoid using time.sleep() in tests. Instead, use localstack.utils.sync.retry(..) to poll for the expected state. This makes tests more robust and avoids unnecessary delays when resources become available faster than expected.

Fixing or Enhancing Logic in the Proxy

Notes:

  • The AWS proxy is running as a LocalStack Extension, and the tests are currently set up in a way that they assume the container to be running with the Extension in dev mode. Hence, in order to make actual changes to the proxy logic, we'll need to restart the LocalStack main container. You can either ask me (the user) to restart the container whenever you're making changes in the core logic, or alternatively remove the localstack-main container, and then run EXTENSION_DEV_MODE=1 DEBUG=1 localstack start -d again to restart the container, which may reveal some error logs, stack traces, etc.
  • If the proxy raises errors or something seems off, you can grab and parse the output of the LocalStack container via localstack logs.