Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

Feat/s3 files service v1.1.48 (#176)

Nahuel Nucera6b6abc8e1ba2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Added
diff --git a/README.md b/README.md
index 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.py
index 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_sts
from 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.py
index 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.py
new file mode 100644
index 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.toml
index 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" }