Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
Feat/s3 files service v1.1.48 (#176)
Nahuel Nucera6b6abc8e1ba2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cbf7ffa9..c2eb229c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,15 +7,19 @@ Versioning follows [Semantic Versioning](https://semver.org/).----## [Unreleased]+## [1.1.48] — 2026-04-07### Added-- **Step Functions query-protocol `aws-sdk:*` task dispatcher** — Task states can now call query-protocol AWS services (RDS, SQS, SNS, ElastiCache, EC2, IAM, STS, CloudWatch) via `arn:aws:states:::aws-sdk:<service>:<action>` resource ARNs. Converts JSON parameters to query-encoded form data and parses XML responses back to JSON. Contributed by @jayjanssen+- **S3 Files service (21 operations)** — CreateFileSystem, GetFileSystem, ListFileSystems, DeleteFileSystem, CreateMountTarget, GetMountTarget, ListMountTargets, UpdateMountTarget, DeleteMountTarget, CreateAccessPoint, GetAccessPoint, ListAccessPoints, DeleteAccessPoint, policies, synchronization config, tagging. First emulator to support AWS S3 Files (launched April 7 2026). 39 services total.+- **Step Functions query-protocol aws-sdk:* dispatcher** — extends the generic aws-sdk dispatcher to support query-protocol services: RDS, SQS, SNS, ElastiCache, EC2, IAM, STS, CloudWatch. XML responses automatically converted to JSON. Contributed by @jayjanssen (#174)+- **Cognito RSA JWT signing** — tokens now signed with the RSA private key matching the JWKS endpoint. Adds `username` claim to access tokens. Contributed by @MartinsMLX (#172)### Tests-- 4 new tests: `aws-sdk:rds` Step Functions task dispatch — CreateDBCluster+DescribeDBClusters, CreateDBInstance+DescribeDBInstances, ModifyDBCluster, and error propagation for missing clusters. Contributed by @jayjanssen+- Comprehensive aws-sdk:secretsmanager SFN task dispatch coverage. Contributed by @jayjanssen (#173)+- 1054 tests total---+## [1.1.47] — 2026-04-07### Addeddiff --git a/README.md b/README.mdindex d6fb384a..e3eb6d13 100644--- a/README.md+++ b/README.md@@ -343,6 +343,7 @@ Unsupported resource types fail with `CREATE_FAILED` (or `ROLLBACK_COMPLETE` if| **ECR** | CreateRepository, DescribeRepositories, DeleteRepository, ListImages, DescribeImages, PutImage, BatchGetImage, BatchDeleteImage, GetAuthorizationToken, GetRepositoryPolicy, SetRepositoryPolicy, DeleteRepositoryPolicy, PutLifecyclePolicy, GetLifecyclePolicy, DeleteLifecyclePolicy, ListTagsForResource, TagResource, UntagResource, PutImageTagMutability, PutImageScanningConfiguration, DescribeRegistry, GetDownloadUrlForLayer, BatchCheckLayerAvailability, InitiateLayerUpload, UploadLayerPart, CompleteLayerUpload | In-memory image registry; Docker V2 manifest support; authorization token generation; lifecycle policies; tag mutability; Pro-only on LocalStack — free here || **AppSync** | CreateGraphQLApi, GetGraphQLApi, ListGraphQLApis, UpdateGraphQLApi, DeleteGraphQLApi, CreateApiKey, DeleteApiKey, ListApiKeys, CreateDataSource, GetDataSource, ListDataSources, DeleteDataSource, CreateResolver, GetResolver, ListResolvers, DeleteResolver, CreateType, ListTypes, GetType, TagResource, UntagResource, ListTagsForResource | Control plane + data plane; GraphQL queries/mutations execute against DynamoDB resolvers (create/get/list/update/delete); Lambda resolvers supported; designed for Amplify/CDK CRUD patterns — not a full GraphQL spec engine || **Cloud Map** | CreateHttpNamespace, CreatePrivateDnsNamespace, CreatePublicDnsNamespace, GetNamespace, ListNamespaces, DeleteNamespace, UpdateHttpNamespace, UpdatePrivateDnsNamespace, UpdatePublicDnsNamespace, CreateService, GetService, ListServices, DeleteService, UpdateService, RegisterInstance, DeregisterInstance, DiscoverInstances, DiscoverInstancesRevision, ListInstances, GetInstancesHealthStatus, UpdateInstanceCustomHealthStatus, GetServiceAttributes, UpdateServiceAttributes, DeleteServiceAttributes, GetOperation, ListOperations, TagResource, UntagResource, ListTagsForResource | DNS namespaces create Route53 hosted zones; operation tracking; Terraform `aws_service_discovery_*` compatible |+| **S3 Files** | CreateFileSystem, GetFileSystem, ListFileSystems, DeleteFileSystem, CreateMountTarget, GetMountTarget, ListMountTargets, UpdateMountTarget, DeleteMountTarget, CreateAccessPoint, GetAccessPoint, ListAccessPoints, DeleteAccessPoint, GetFileSystemPolicy, PutFileSystemPolicy, DeleteFileSystemPolicy, GetSynchronizationConfiguration, PutSynchronizationConfiguration, TagResource, UntagResource, ListTagsForResource | 21 operations; control plane for the new S3 Files service (launched April 2026); file systems, mount targets, access points, policies |---@@ -799,6 +800,7 @@ See [`Testcontainers/java-testcontainers`](Testcontainers/java-testcontainers),| **CloudFront** | ✅ | Paid | ✅ || **AppSync** | ✅ | NO | ✅ || **Cloud Map** | ✅ | ❌ | ✅ |+| **S3 Files** | ✅ | ❌ | ❌ || Cost | **Free forever** | Was free, now paid | $35+/mo || Docker image size | ~250MB | ~1GB | ~1GB || Memory at idle | ~40MB | ~500MB | ~500MB |diff --git a/ministack/app.py b/ministack/app.pyindex 3fae9d13..7b1e1c6f 100644--- a/ministack/app.py+++ b/ministack/app.py@@ -76,6 +76,7 @@ from ministack.services import (waf,cloudfront,servicediscovery,+ s3files,)from ministack.services import iam_stsfrom ministack.services.iam_sts import handle_iam_request, handle_sts_request@@ -126,6 +127,7 @@ SERVICE_HANDLERS = {"cloudfront": cloudfront.handle_request,"appsync": appsync.handle_request,"servicediscovery": servicediscovery.handle_request,+ "s3files": s3files.handle_request,}SERVICE_NAME_ALIASES = {@@ -180,7 +182,7 @@ BANNER = r"""SSM, EventBridge, Kinesis, CloudWatch, SES, SES v2, ACM, WAF v2, Step Functions,ECS, RDS, ElastiCache, Glue, Athena, API Gateway, Firehose, Route53,Cognito, EC2, EMR, EBS, EFS, ALB/ELBv2, CloudFormation, KMS, ECR, CloudFront,- AppSync, Cloud Map+ AppSync, Cloud Map, S3 Files"""@@ -606,6 +608,7 @@ async def _handle_lifespan(scope, receive, send):"ses": ses.get_state,"ses_v2": ses_v2.get_state,"servicediscovery": servicediscovery.get_state,+ "s3files": s3files.get_state,})await send({"type": "lifespan.shutdown.complete"})return@@ -742,6 +745,7 @@ def _reset_all_state():(ecr, ecr.reset),(appsync, appsync.reset),(servicediscovery, servicediscovery.reset),+ (s3files, s3files.reset),]:try:fn()diff --git a/ministack/core/router.py b/ministack/core/router.pyindex 68e069af..bcf0f051 100644--- a/ministack/core/router.py+++ b/ministack/core/router.py@@ -172,6 +172,11 @@ SERVICE_PATTERNS = {"host_patterns": [r"servicediscovery\."],"credential_scope": "servicediscovery",},+ "s3files": {+ "host_patterns": [r"s3files\."],+ "credential_scope": "s3files",+ "path_prefixes": ["/file-systems", "/mount-targets", "/access-points"],+ },}@@ -225,6 +230,7 @@ def detect_service(method: str, path: str, headers: dict, query_params: dict) ->"cloudfront": "cloudfront","appsync": "appsync","servicediscovery": "servicediscovery",+ "s3files": "s3files",}if svc_name in scope_map:return scope_map[svc_name]diff --git a/ministack/services/s3files.py b/ministack/services/s3files.pynew file mode 100644index 00000000..9033e613--- /dev/null+++ b/ministack/services/s3files.py@@ -0,0 +1,380 @@+"""+Amazon S3 Files Service Emulator.+REST/JSON API — file systems, mount targets, access points.++Supports:+ File Systems: CreateFileSystem, GetFileSystem, ListFileSystems, DeleteFileSystem+ Mount Targets: CreateMountTarget, GetMountTarget, ListMountTargets,+ DeleteMountTarget, UpdateMountTarget+ Access Points: CreateAccessPoint, GetAccessPoint, ListAccessPoints, DeleteAccessPoint+ Policies: GetFileSystemPolicy, PutFileSystemPolicy, DeleteFileSystemPolicy+ Sync: GetSynchronizationConfiguration, PutSynchronizationConfiguration+ Tags: TagResource, UntagResource, ListTagsForResource+"""++import copy+import json+import logging+import os+import time++from ministack.core.persistence import PERSIST_STATE, load_state+from ministack.core.responses import error_response_json, json_response, new_uuid++logger = logging.getLogger("s3files")++ACCOUNT_ID = os.environ.get("MINISTACK_ACCOUNT_ID", "000000000000")+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")++_file_systems: dict = {}+_mount_targets: dict = {}+_access_points: dict = {}+_policies: dict = {}+_sync_configs: dict = {}+_tags: dict = {}+++def get_state():+ return copy.deepcopy({+ "file_systems": _file_systems,+ "mount_targets": _mount_targets,+ "access_points": _access_points,+ "policies": _policies,+ "sync_configs": _sync_configs,+ "tags": _tags,+ })+++def restore_state(data):+ if not data:+ return+ _file_systems.update(data.get("file_systems", {}))+ _mount_targets.update(data.get("mount_targets", {}))+ _access_points.update(data.get("access_points", {}))+ _policies.update(data.get("policies", {}))+ _sync_configs.update(data.get("sync_configs", {}))+ _tags.update(data.get("tags", {}))+++_restored = load_state("s3files")+if _restored:+ restore_state(_restored)+++def reset():+ _file_systems.clear()+ _mount_targets.clear()+ _access_points.clear()+ _policies.clear()+ _sync_configs.clear()+ _tags.clear()+++def _arn(resource_type, resource_id):+ return f"arn:aws:s3files:{REGION}:{ACCOUNT_ID}:{resource_type}/{resource_id}"+++def _now_iso():+ return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())+++# ---------------------------------------------------------------------------+# Request handler+# ---------------------------------------------------------------------------++async def handle_request(method, path, headers, body, query_params):+ try:+ data = json.loads(body) if body else {}+ except (json.JSONDecodeError, TypeError):+ data = {}++ parts = [p for p in path.strip("/").split("/") if p]++ # POST /file-systems+ if method == "POST" and parts == ["file-systems"]:+ return _create_file_system(data)++ # GET /file-systems+ if method == "GET" and parts == ["file-systems"]:+ return _list_file_systems(data, query_params)++ # GET /file-systems/{id}+ if method == "GET" and len(parts) == 2 and parts[0] == "file-systems":+ return _get_file_system(parts[1])++ # DELETE /file-systems/{id}+ if method == "DELETE" and len(parts) == 2 and parts[0] == "file-systems":+ return _delete_file_system(parts[1])++ # GET /file-systems/{id}/policy+ if method == "GET" and len(parts) == 3 and parts[0] == "file-systems" and parts[2] == "policy":+ return _get_file_system_policy(parts[1])++ # PUT /file-systems/{id}/policy+ if method == "PUT" and len(parts) == 3 and parts[0] == "file-systems" and parts[2] == "policy":+ return _put_file_system_policy(parts[1], data)++ # DELETE /file-systems/{id}/policy+ if method == "DELETE" and len(parts) == 3 and parts[0] == "file-systems" and parts[2] == "policy":+ return _delete_file_system_policy(parts[1])++ # POST /mount-targets+ if method == "POST" and parts == ["mount-targets"]:+ return _create_mount_target(data)++ # GET /mount-targets+ if method == "GET" and parts == ["mount-targets"]:+ return _list_mount_targets(data, query_params)++ # GET /mount-targets/{id}+ if method == "GET" and len(parts) == 2 and parts[0] == "mount-targets":+ return _get_mount_target(parts[1])++ # PUT /mount-targets/{id}+ if method == "PUT" and len(parts) == 2 and parts[0] == "mount-targets":+ return _update_mount_target(parts[1], data)++ # DELETE /mount-targets/{id}+ if method == "DELETE" and len(parts) == 2 and parts[0] == "mount-targets":+ return _delete_mount_target(parts[1])++ # POST /access-points+ if method == "POST" and parts == ["access-points"]:+ return _create_access_point(data)++ # GET /access-points+ if method == "GET" and parts == ["access-points"]:+ return _list_access_points(data, query_params)++ # GET /access-points/{id}+ if method == "GET" and len(parts) == 2 and parts[0] == "access-points":+ return _get_access_point(parts[1])++ # DELETE /access-points/{id}+ if method == "DELETE" and len(parts) == 2 and parts[0] == "access-points":+ return _delete_access_point(parts[1])++ # GET /file-systems/{id}/synchronization-configuration+ if method == "GET" and len(parts) == 3 and parts[2] == "synchronization-configuration":+ return _get_sync_config(parts[1])++ # PUT /file-systems/{id}/synchronization-configuration+ if method == "PUT" and len(parts) == 3 and parts[2] == "synchronization-configuration":+ return _put_sync_config(parts[1], data)++ # POST /tags/{arn}+ if method == "POST" and len(parts) >= 2 and parts[0] == "tags":+ resource_arn = "/".join(parts[1:])+ return _tag_resource(resource_arn, data)++ # DELETE /tags/{arn}+ if method == "DELETE" and len(parts) >= 2 and parts[0] == "tags":+ resource_arn = "/".join(parts[1:])+ tag_keys = query_params.get("tagKeys", [])+ if isinstance(tag_keys, str):+ tag_keys = [tag_keys]+ return _untag_resource(resource_arn, tag_keys)++ # GET /tags/{arn}+ if method == "GET" and len(parts) >= 2 and parts[0] == "tags":+ resource_arn = "/".join(parts[1:])+ return _list_tags(resource_arn)++ return error_response_json("InvalidRequest", f"Unknown S3 Files route: {method} {path}", 400)+++# ---------------------------------------------------------------------------+# File Systems+# ---------------------------------------------------------------------------++def _create_file_system(data):+ fs_id = "fs-" + new_uuid().replace("-", "")[:17]+ bucket_name = data.get("BucketName", "")+ arn = _arn("file-system", fs_id)+ fs = {+ "FileSystemId": fs_id,+ "FileSystemArn": arn,+ "BucketName": bucket_name,+ "LifeCycleState": "available",+ "CreationTime": _now_iso(),+ "OwnerId": ACCOUNT_ID,+ }+ _file_systems[fs_id] = fs+ logger.info("Created S3 file system %s for bucket %s", fs_id, bucket_name)+ return json_response(fs, 201)+++def _get_file_system(fs_id):+ fs = _file_systems.get(fs_id)+ if not fs:+ return error_response_json("FileSystemNotFound", f"File system {fs_id} not found", 404)+ return json_response(fs)+++def _list_file_systems(data, query_params):+ items = list(_file_systems.values())+ return json_response({"FileSystems": items})+++def _delete_file_system(fs_id):+ if fs_id not in _file_systems:+ return error_response_json("FileSystemNotFound", f"File system {fs_id} not found", 404)+ del _file_systems[fs_id]+ _policies.pop(fs_id, None)+ _sync_configs.pop(fs_id, None)+ return 204, {}, b""+++# ---------------------------------------------------------------------------+# Mount Targets+# ---------------------------------------------------------------------------++def _create_mount_target(data):+ mt_id = "fsmt-" + new_uuid().replace("-", "")[:17]+ fs_id = data.get("FileSystemId", "")+ subnet_id = data.get("SubnetId", "")+ mt = {+ "MountTargetId": mt_id,+ "FileSystemId": fs_id,+ "SubnetId": subnet_id,+ "LifeCycleState": "available",+ "IpAddress": data.get("IpAddress", "10.0.0.1"),+ "VpcId": data.get("VpcId", "vpc-00000001"),+ "AvailabilityZone": data.get("AvailabilityZone", f"{REGION}a"),+ }+ _mount_targets[mt_id] = mt+ logger.info("Created mount target %s for fs %s", mt_id, fs_id)+ return json_response(mt, 201)+++def _get_mount_target(mt_id):+ mt = _mount_targets.get(mt_id)+ if not mt:+ return error_response_json("MountTargetNotFound", f"Mount target {mt_id} not found", 404)+ return json_response(mt)+++def _list_mount_targets(data, query_params):+ fs_id = query_params.get("FileSystemId", [""])[0] if isinstance(query_params.get("FileSystemId"), list) else query_params.get("FileSystemId", "")+ items = list(_mount_targets.values())+ if fs_id:+ items = [mt for mt in items if mt.get("FileSystemId") == fs_id]+ return json_response({"MountTargets": items})+++def _update_mount_target(mt_id, data):+ mt = _mount_targets.get(mt_id)+ if not mt:+ return error_response_json("MountTargetNotFound", f"Mount target {mt_id} not found", 404)+ for key in ("SubnetId", "IpAddress", "SecurityGroups"):+ if key in data:+ mt[key] = data[key]+ return json_response(mt)+++def _delete_mount_target(mt_id):+ if mt_id not in _mount_targets:+ return error_response_json("MountTargetNotFound", f"Mount target {mt_id} not found", 404)+ del _mount_targets[mt_id]+ return 204, {}, b""+++# ---------------------------------------------------------------------------+# Access Points+# ---------------------------------------------------------------------------++def _create_access_point(data):+ ap_id = "fsap-" + new_uuid().replace("-", "")[:17]+ fs_id = data.get("FileSystemId", "")+ arn = _arn("access-point", ap_id)+ ap = {+ "AccessPointId": ap_id,+ "AccessPointArn": arn,+ "FileSystemId": fs_id,+ "Name": data.get("Name", ""),+ "LifeCycleState": "available",+ }+ _access_points[ap_id] = ap+ return json_response(ap, 201)+++def _get_access_point(ap_id):+ ap = _access_points.get(ap_id)+ if not ap:+ return error_response_json("AccessPointNotFound", f"Access point {ap_id} not found", 404)+ return json_response(ap)+++def _list_access_points(data, query_params):+ items = list(_access_points.values())+ return json_response({"AccessPoints": items})+++def _delete_access_point(ap_id):+ if ap_id not in _access_points:+ return error_response_json("AccessPointNotFound", f"Access point {ap_id} not found", 404)+ del _access_points[ap_id]+ return 204, {}, b""+++# ---------------------------------------------------------------------------+# Policies+# ---------------------------------------------------------------------------++def _get_file_system_policy(fs_id):+ policy = _policies.get(fs_id)+ if not policy:+ return error_response_json("PolicyNotFound", f"No policy for file system {fs_id}", 404)+ return json_response({"FileSystemId": fs_id, "Policy": policy})+++def _put_file_system_policy(fs_id, data):+ if fs_id not in _file_systems:+ return error_response_json("FileSystemNotFound", f"File system {fs_id} not found", 404)+ _policies[fs_id] = data.get("Policy", "")+ return json_response({"FileSystemId": fs_id, "Policy": _policies[fs_id]})+++def _delete_file_system_policy(fs_id):+ _policies.pop(fs_id, None)+ return 204, {}, b""+++# ---------------------------------------------------------------------------+# Synchronization Configuration+# ---------------------------------------------------------------------------++def _get_sync_config(fs_id):+ config = _sync_configs.get(fs_id, {})+ return json_response({"FileSystemId": fs_id, "SynchronizationConfiguration": config})+++def _put_sync_config(fs_id, data):+ if fs_id not in _file_systems:+ return error_response_json("FileSystemNotFound", f"File system {fs_id} not found", 404)+ _sync_configs[fs_id] = data.get("SynchronizationConfiguration", data)+ return json_response({"FileSystemId": fs_id, "SynchronizationConfiguration": _sync_configs[fs_id]})+++# ---------------------------------------------------------------------------+# Tags+# ---------------------------------------------------------------------------++def _tag_resource(resource_arn, data):+ tags = _tags.setdefault(resource_arn, [])+ for tag in data.get("Tags", []):+ existing = next((t for t in tags if t["Key"] == tag["Key"]), None)+ if existing:+ existing["Value"] = tag["Value"]+ else:+ tags.append(tag)+ return json_response({})+++def _untag_resource(resource_arn, tag_keys):+ _tags[resource_arn] = [t for t in _tags.get(resource_arn, []) if t["Key"] not in tag_keys]+ return json_response({})+++def _list_tags(resource_arn):+ return json_response({"Tags": _tags.get(resource_arn, [])})diff --git a/pyproject.toml b/pyproject.tomlindex 78f0616c..fb909d8c 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"[project]name = "ministack"-version = "1.1.47"+version = "1.1.48"description = "Free, open-source local AWS emulator — drop-in LocalStack replacement"readme = "README.md"license = { file = "LICENSE" }