Light, fluffy, and always free - The AWS Local Emulator alternative
feat(s3): resolve index documents for static-website directory requests (#1815)
Alex Banna6d829ff7a460
diff --git a/docs/services/s3.md b/docs/services/s3.mdindex 67f6b04afb..f6cdb03e28 100644--- a/docs/services/s3.md+++ b/docs/services/s3.md@@ -20,12 +20,26 @@| **Encryption** | PutBucketEncryption, GetBucketEncryption, DeleteBucketEncryption || **Notifications** | PutBucketNotification, GetBucketNotification || **Object Lock** | PutObjectLockConfiguration, GetObjectLockConfiguration, PutObjectRetention, GetObjectRetention, PutObjectLegalHold, GetObjectLegalHold |+| **Website** | PutBucketWebsite, GetBucketWebsite, DeleteBucketWebsite || **Pre-signed URLs** | Generates and validates pre-signed GET/PUT URLs || **S3 Select** | SelectObjectContent || **Public Access Block** | PutPublicAccessBlock, GetPublicAccessBlock, DeletePublicAccessBlock |**RestoreObject** is accepted but stubbed: Floci validates the request and returns `202 Accepted`, but no restore state machine runs.+## Website Hosting++Static website requests use a bucket website hostname such as+`http://my-bucket.s3-website-us-east-1.localhost:4566/`. Floci supports:++- GET and HEAD requests through website hostnames+- index-document resolution for the site root and slash-terminated prefixes+- `302` redirects that append a slash when an index document exists below a prefix+- configured error documents and the default website error response++HEAD returns the same status and object metadata as GET without a response body.+Redirect-all and advanced routing-rule configurations are not implemented.+## Range Reads`GetObject` supports standard `Range: bytes=` requests. Partial responses return `206`, `Content-Range`, `Content-Length`, `Accept-Ranges: bytes`, and object metadata. Whole-object checksum headers are omitted on ranged responses because the stored checksum covers the full object, not the returned byte slice. Full-object and ranged reads stream object bytes from storage instead of materializing the response body first.@@ -134,7 +148,6 @@ When `FLOCI_SERVICES_ATHENA_MOCK=true` is set, Athena queries are stubbed but flThese AWS S3 features have no handler in Floci. Calls will return an error (typically `404` or `NoSuchBucket`-style):- Replication (`PutBucketReplication`, `GetBucketReplication`, `DeleteBucketReplication`)-- Website hosting (`PutBucketWebsite`, `GetBucketWebsite`, `DeleteBucketWebsite`)- Access logging (`PutBucketLogging`, `GetBucketLogging`)- Request payment (`PutBucketRequestPayment`, `GetBucketRequestPayment`)- Intelligent-Tiering configurationsdiff --git a/src/main/java/io/github/hectorvent/floci/services/s3/S3Controller.java b/src/main/java/io/github/hectorvent/floci/services/s3/S3Controller.javaindex 560483777f..e5cfd05437 100644--- a/src/main/java/io/github/hectorvent/floci/services/s3/S3Controller.java+++ b/src/main/java/io/github/hectorvent/floci/services/s3/S3Controller.java@@ -231,6 +231,12 @@ public class S3Controller {try {S3Service.RequestAuthorization authorization = S3RequestAuthorizationParser.parseIfRequired(s3Service.isAuthEnforced(), httpHeaders, uriInfo);+ if (isWebsiteRequest(httpHeaders, uriInfo)) {+ Response websiteResponse = serveWebsiteObject(bucket, "", authorization);+ if (websiteResponse != null) {+ return headOnlyResponse(websiteResponse);+ }+ }s3Service.authorizeBucketRead(bucket, "s3:ListBucket", authorization);s3Service.headBucket(bucket);String bucketRegion = s3Service.getBucketRegion(bucket);@@ -497,35 +503,15 @@ public class S3Controller {return Response.ok(s3Service.getBucketRequestPayment(bucket)).build();}- // --- Website Hosting Redirection Logic ---- if (isWebsiteRequest(httpHeaders, uriInfo) && (uriInfo.getQueryParameters().isEmpty() || (uriInfo.getQueryParameters().size() == 1 && hasQueryParam(uriInfo, "list-type")))) {- try {- WebsiteConfiguration webConfig = s3Service.getBucketWebsite(bucket);- if (webConfig.getIndexDocument() != null) {- try {- s3Service.authorizeGetObject(bucket, webConfig.getIndexDocument(), null, authorization);- S3Object indexObj = s3Service.getObject(bucket, webConfig.getIndexDocument());- return Response.ok(indexObj.getData())- .type(indexObj.getContentType())- .header("Content-Length", indexObj.getSize())- .header("ETag", indexObj.getETag())- .header("x-amz-website-redirect-location", "index")- .build();- } catch (AwsException e) {- if (!isWebsiteErrorDocumentTrigger(e)) {- throw e;- }- Response r = serveErrorDocument(bucket, webConfig, authorization, e.getHttpStatus());- if (r != null) {- return r;- }- }- }- } catch (AwsException e) {- if (!"NoSuchWebsiteConfiguration".equals(e.getErrorCode())) {- throw e;- }- // Bucket is not a website, continue to listObjects+ // --- S3 static-website index resolution (site root) ---+ // A website endpoint has no S3 REST API, so it serves the index document for the site root+ // regardless of any query string — e.g. a single-page-app OAuth callback GET+ // /?code=...&state=... must return index.html, not a ListObjects response. (?list-type and+ // other sub-resource queries only reach the REST endpoint, never a website host.)+ if (isWebsiteRequest(httpHeaders, uriInfo)) {+ Response website = serveWebsiteObject(bucket, "", authorization);+ if (website != null) {+ return website;}}@@ -746,6 +732,13 @@ public class S3Controller {authorization = S3RequestAuthorizationParser.parseIfRequired(s3Service.isAuthEnforced(), httpHeaders, uriInfo);+ if (isWebsiteRequest(httpHeaders, uriInfo)) {+ Response website = serveWebsiteObject(bucket, key, authorization);+ if (website != null) {+ return website;+ }+ }+if (uploadId != null) {s3Service.authorizeObjectRead(bucket, key, versionId, "s3:ListMultipartUploadParts", authorization);return handleListParts(bucket, key, uploadId, maxPartsQuery, partNumberMarkerQuery);@@ -816,16 +809,9 @@ public class S3Controller {} catch (AwsException e) {emitCloudTrailEvent("GetObject", bucket, key, 0L, 0L, e.getErrorCode(), e.getMessage());if (isWebsiteErrorDocumentTrigger(e) && isWebsiteRequest(httpHeaders, uriInfo)) {- try {- WebsiteConfiguration webConfig = s3Service.getBucketWebsite(bucket);- Response r = serveErrorDocument(bucket, webConfig, authorization, e.getHttpStatus());- if (r != null) {- return r;- }- } catch (AwsException websiteException) {- if (!"NoSuchWebsiteConfiguration".equals(websiteException.getErrorCode())) {- return xmlErrorResponse(websiteException);- }+ Response websiteError = serveWebsiteErrorResponse(bucket, authorization, e);+ if (websiteError != null) {+ return websiteError;}}return xmlErrorResponse(e);@@ -964,10 +950,17 @@ public class S3Controller {@HeaderParam("x-amz-checksum-mode") String checksumMode,@Context UriInfo uriInfo,@Context HttpHeaders httpHeaders) {+ S3Service.RequestAuthorization authorization = S3Service.RequestAuthorization.unsigned();try {key = extractObjectKey(uriInfo, bucket);- S3Service.RequestAuthorization authorization = S3RequestAuthorizationParser.parseIfRequired(+ authorization = S3RequestAuthorizationParser.parseIfRequired(s3Service.isAuthEnforced(), httpHeaders, uriInfo);+ if (isWebsiteRequest(httpHeaders, uriInfo)) {+ Response websiteResponse = serveWebsiteObject(bucket, key, authorization);+ if (websiteResponse != null) {+ return headOnlyResponse(websiteResponse);+ }+ }s3Service.authorizeGetObject(bucket, key, versionId, authorization);S3Object obj = s3Service.headObject(bucket, key, versionId);@@ -1002,6 +995,12 @@ public class S3Controller {return resp.build();} catch (AwsException e) {emitCloudTrailEvent("HeadObject", bucket, key, 0L, 0L, e.getErrorCode(), e.getMessage());+ if (isWebsiteErrorDocumentTrigger(e) && isWebsiteRequest(httpHeaders, uriInfo)) {+ Response websiteError = serveWebsiteErrorResponse(bucket, authorization, e);+ if (websiteError != null) {+ return headOnlyResponse(websiteError);+ }+ }return xmlErrorResponse(e);}}@@ -2193,12 +2192,104 @@ public class S3Controller {return host != null && host.contains("s3-website");}+ private static Response headOnlyResponse(Response response) {+ return Response.fromResponse(response)+ .entity(null)+ .build();+ }++ /**+ * Applies S3 static-website index-document resolution to a website-endpoint GET, mirroring how the+ * real {@code <bucket>.s3-website-<region>.amazonaws.com} endpoint serves a site:+ * <ul>+ * <li>a "directory" request (the site root, or any key ending in {@code /}) serves the index+ * document for that prefix — e.g. {@code /docs/} serves {@code docs/index.html};</li>+ * <li>a non-slash path that is not itself an object but has an index document underneath it is a+ * folder, so it 302-redirects to the slash-terminated form (so the page's relative asset URLs+ * resolve against the right base);</li>+ * <li>a missing index document returns the configured error document, or S3's default+ * website error response when no custom document is configured.</li>+ * </ul>+ * Returns {@code null} when the request should be served by the normal object path — i.e. an exact+ * object hit, or a bucket that has no website configuration at all. The index read is authorized+ * (a no-op unless S3 auth enforcement is enabled), matching the object-serving path.+ */+ private Response serveWebsiteObject(String bucket, String key,+ S3Service.RequestAuthorization authorization) {+ WebsiteConfiguration cfg;+ try {+ cfg = s3Service.getBucketWebsite(bucket);+ } catch (AwsException e) {+ // Only "no website configuration" means fall through to normal handling; a real error+ // (e.g. NoSuchBucket) must propagate rather than be masked as "not a website".+ if (!"NoSuchWebsiteConfiguration".equals(e.getErrorCode())) {+ throw e;+ }+ return null;+ }+ String index = cfg.getIndexDocument();+ if (index == null) {+ return null;+ }+ // The routing layer strips a trailing slash from the object key, so recover the "directory"+ // intent from the raw request path: a trailing slash (or the site root) means "serve this+ // prefix's index document"; the prefix is the key without any trailing slash.+ var request = currentVertxRequest.getCurrent().request();+ String rawPath = request.path();+ boolean directory = key.isEmpty() || rawPath.endsWith("/");+ String prefix = key.endsWith("/") ? key.substring(0, key.length() - 1) : key;++ if (directory) {+ String indexKey = prefix.isEmpty() ? index : prefix + "/" + index;+ try {+ s3Service.authorizeGetObject(bucket, indexKey, null, authorization);+ S3Object indexObj = s3Service.headObject(bucket, indexKey, null);+ // A website endpoint serves the index document with no response-header overrides and no+ // checksum headers (no viewer sends response-* or x-amz-checksum-mode to a website endpoint).+ return fullObjectResponse(bucket, indexKey, null, indexObj,+ new ResponseHeaderOverrides(null, null, null, null, null, null), false);+ } catch (AwsException e) {+ if (!isWebsiteErrorDocumentTrigger(e)) {+ throw e;+ }+ Response err = serveErrorDocument(bucket, cfg, authorization, e.getHttpStatus());+ return err != null ? err : xmlErrorResponse(e);+ }+ }+ // Not slash-terminated: an exact object is served by the normal path; a prefix that exists only+ // as a "folder" (an index document lives beneath it) 302-redirects to the slash-terminated form+ // so the page's relative asset URLs resolve against the right base (matching real S3).+ if (!s3Service.objectExists(bucket, prefix) && s3Service.objectExists(bucket, prefix + "/" + index)) {+ // The query string is deliberately dropped: real S3 answers+ // GET /photos?code=abc&state=xyz with a bare "Location: /photos/" (verified against a+ // live website endpoint in us-east-1, same for HEAD and for nested prefixes).+ return Response.status(Response.Status.FOUND)+ .header("Location", rawPath + "/")+ .build();+ }+ return null;+ }++ private Response serveWebsiteErrorResponse(String bucket,+ S3Service.RequestAuthorization authorization,+ AwsException cause) {+ try {+ WebsiteConfiguration webConfig = s3Service.getBucketWebsite(bucket);+ return serveErrorDocument(bucket, webConfig, authorization, cause.getHttpStatus());+ } catch (AwsException websiteException) {+ if (!"NoSuchWebsiteConfiguration".equals(websiteException.getErrorCode())) {+ return xmlErrorResponse(websiteException);+ }+ return null;+ }+ }+private Response serveErrorDocument(String bucket, WebsiteConfiguration cfg,S3Service.RequestAuthorization authorization, int status) {+ int responseStatus = status == 403 ? 403 : 404;if (cfg.getErrorDocument() == null) {- return null;+ return defaultWebsiteErrorResponse(responseStatus);}- int responseStatus = status == 403 ? 403 : 404;try {s3Service.authorizeGetObject(bucket, cfg.getErrorDocument(), null, authorization);S3Object err = s3Service.getObject(bucket, cfg.getErrorDocument());@@ -2213,15 +2304,21 @@ public class S3Controller {if (!isWebsiteErrorDocumentTrigger(e)) {throw e;}- return Response.status(responseStatus)- .entity(defaultWebsiteErrorBody(responseStatus))- .type(MediaType.TEXT_HTML)- .header("x-amz-error-code", websiteErrorCode(responseStatus))- .header("x-amz-error-message", websiteErrorMessage(responseStatus))- .build();+ return defaultWebsiteErrorResponse(responseStatus);}}+ private static Response defaultWebsiteErrorResponse(int status) {+ String body = defaultWebsiteErrorBody(status);+ return Response.status(status)+ .entity(body)+ .type(MediaType.TEXT_HTML)+ .header("Content-Length", body.getBytes(StandardCharsets.UTF_8).length)+ .header("x-amz-error-code", websiteErrorCode(status))+ .header("x-amz-error-message", websiteErrorMessage(status))+ .build();+ }+private static boolean isWebsiteErrorDocumentTrigger(AwsException e) {return "NoSuchKey".equals(e.getErrorCode()) || "AccessDenied".equals(e.getErrorCode());}diff --git a/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java b/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.javaindex 39ff858652..d2d82782cc 100644--- a/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java+++ b/src/main/java/io/github/hectorvent/floci/services/s3/S3Service.java@@ -639,6 +639,22 @@ public class S3Service implements Resettable {return getObjectMetadata(bucketName, key, versionId);}+ /** Returns true when the (latest-version) object exists, without throwing on a miss. */+ public boolean objectExists(String bucketName, String key) {+ try {+ getObjectMetadata(bucketName, key, null);+ return true;+ } catch (AwsException e) {+ // Only a genuine miss means "does not exist"; surface any other storage error (e.g.+ // NoSuchBucket) instead of masking it as absent, which would let callers act on a wrong+ // answer (e.g. issue a website redirect that hides the real failure).+ if ("NoSuchKey".equals(e.getErrorCode()) || "NoSuchVersion".equals(e.getErrorCode())) {+ return false;+ }+ throw e;+ }+ }+public InputStream openObjectStream(String bucketName, String key, String versionId) {getObjectMetadata(bucketName, key, versionId);if (inMemory) {diff --git a/src/test/java/io/github/hectorvent/floci/services/s3/S3ServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/s3/S3ServiceTest.javaindex bb77686eb2..3fcc70b4cf 100644--- a/src/test/java/io/github/hectorvent/floci/services/s3/S3ServiceTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/s3/S3ServiceTest.java@@ -74,6 +74,21 @@ class S3ServiceTest {assertNull(s3Service.getBucketRegion("default-bucket"));}+ @Test+ void objectExistsReturnsFalseForMissingKey() {+ s3Service.createBucket("exists-bucket", "us-east-1");+ assertFalse(s3Service.objectExists("exists-bucket", "no-such-key"));+ }++ @Test+ void objectExistsRethrowsWhenBucketMissing() {+ // A missing key returns false, but a non-"not found" storage error (here NoSuchBucket) must+ // surface rather than be masked as "object absent".+ AwsException e = assertThrows(AwsException.class,+ () -> s3Service.objectExists("no-such-bucket", "any-key"));+ assertEquals("NoSuchBucket", e.getErrorCode());+ }+@Testvoid createDuplicateBucketInUsEast1IsIdempotent() {Bucket first = s3Service.createBucket("test-bucket", "us-east-1");diff --git a/src/test/java/io/github/hectorvent/floci/services/s3/S3WebsiteIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/s3/S3WebsiteIntegrationTest.javaindex 963a3e3e99..f6425bca05 100644--- a/src/test/java/io/github/hectorvent/floci/services/s3/S3WebsiteIntegrationTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/s3/S3WebsiteIntegrationTest.java@@ -129,6 +129,43 @@ class S3WebsiteIntegrationTest {.body(equalTo("<html><body>Hello Website</body></html>"));}+ @Test+ @Order(12)+ void indexServedForRootEvenWithQueryString() {+ // A website endpoint has no S3 REST API, so a query string on the site root (e.g. an SPA+ // OAuth callback GET /?code=...&state=...) must still serve the index document rather than+ // fall through to a ListObjects response.+ given()+ .header("Host", websiteHost())+ .queryParam("code", "abc")+ .queryParam("state", "xyz")+ .when()+ .get("/")+ .then()+ .statusCode(200)+ .contentType("text/html")+ .body(equalTo("<html><body>Hello Website</body></html>"));+ }++ @Test+ @Order(13)+ void headWebsiteRootServesIndexMetadataWithoutBody() {+ given()+ .header("Host", websiteHost())+ .queryParam("code", "abc")+ .queryParam("state", "xyz")+ .when()+ .head("/")+ .then()+ .statusCode(200)+ .contentType("text/html")+ .header("Content-Length", equalTo("39"))+ .header("ETag", not(isEmptyOrNullString()))+ .header("Last-Modified", not(isEmptyOrNullString()))+ .header("Accept-Ranges", equalTo("bytes"))+ .body(emptyString());+ }+@Test@Order(9)void missingKeyServesErrorDocument() {@@ -182,7 +219,198 @@ class S3WebsiteIntegrationTest {}@Test- @Order(12)+ @Order(14)+ void uploadSubdirectoryIndex() {+ given()+ .contentType("text/html")+ .body("<html><body>Docs Home</body></html>")+ .when()+ .put("/" + BUCKET + "/docs/index.html")+ .then()+ .statusCode(200);+ }++ @Test+ @Order(15)+ void directoryRequestServesIndexDocumentWithQueryString() {+ // GET /docs/ on the website endpoint serves docs/index.html (AWS index-document resolution),+ // not the error document. Website endpoints expose only object GET/HEAD behavior, so a query+ // name that is an S3 REST subresource must remain an ordinary website query string.+ given()+ .header("Host", websiteHost())+ .queryParam("tagging", "")+ .when()+ .get("/docs/")+ .then()+ .statusCode(200)+ .contentType("text/html")+ .body(equalTo("<html><body>Docs Home</body></html>"));+ }++ @Test+ @Order(16)+ void directoryWithoutTrailingSlashRedirects() {+ // GET /docs (a folder, not an object) 302-redirects to /docs/ so the page's relative asset+ // URLs resolve against the correct base — matching real S3 website behavior.+ given()+ .header("Host", websiteHost())+ .redirects().follow(false)+ .when()+ .get("/docs")+ .then()+ .statusCode(302)+ .header("Location", equalTo("/docs/"));+ }++ /**+ * Real S3 drops the query string from the folder redirect: a live us-east-1 website endpoint+ * answers {@code GET /photos?code=abc&state=xyz} with a bare {@code Location: /photos/}.+ * An SPA relying on the callback parameters surviving the redirect has to handle that on AWS,+ * so the emulator matches rather than improving on it.+ */+ @Test+ @Order(17)+ void directoryRedirectDropsQueryStringLikeRealS3() {+ given()+ .header("Host", websiteHost())+ .redirects().follow(false)+ .when()+ .get("/docs?code=abc&state=xyz")+ .then()+ .statusCode(302)+ .header("Location", equalTo("/docs/"));+ }++ @Test+ @Order(18)+ void nestedDirectoryServesIndexDocument() {+ given()+ .contentType("text/html")+ .body("<html><body>Nested</body></html>")+ .when()+ .put("/" + BUCKET + "/a/b/index.html")+ .then()+ .statusCode(200);++ given()+ .header("Host", websiteHost())+ .when()+ .get("/a/b/")+ .then()+ .statusCode(200)+ .body(equalTo("<html><body>Nested</body></html>"));+ }++ @Test+ @Order(19)+ void directoryWithoutIndexServesErrorDocument() {+ // A trailing-slash request whose prefix has no index document falls back to the error document.+ given()+ .header("Host", websiteHost())+ .when()+ .get("/no-such-dir/")+ .then()+ .statusCode(404)+ .contentType("text/html")+ .header("x-amz-error-code", "NoSuchKey")+ .body(equalTo("<html><body>Custom Error</body></html>"));+ }++ @Test+ @Order(20)+ void headWebsiteDirectoryServesIndexMetadataWithoutBody() {+ given()+ .header("Host", websiteHost())+ .when()+ .head("/docs/")+ .then()+ .statusCode(200)+ .contentType("text/html")+ .header("Content-Length", equalTo("35"))+ .header("ETag", not(isEmptyOrNullString()))+ .header("Last-Modified", not(isEmptyOrNullString()))+ .header("Accept-Ranges", equalTo("bytes"))+ .body(emptyString());+ }++ @Test+ @Order(21)+ void headWebsiteDirectoryWithoutTrailingSlashRedirectsWithoutBody() {+ given()+ .header("Host", websiteHost())+ .redirects().follow(false)+ .when()+ .head("/docs?code=abc&state=xyz")+ .then()+ .statusCode(302)+ .header("Location", equalTo("/docs/"))+ .body(emptyString());+ }++ @Test+ @Order(22)+ void headWebsiteMissingKeyServesErrorMetadataWithoutBody() {+ given()+ .header("Host", websiteHost())+ .when()+ .head("/missing-page")+ .then()+ .statusCode(404)+ .contentType("text/html")+ .header("Content-Length", equalTo("38"))+ .header("x-amz-error-code", equalTo("NoSuchKey"))+ .header("x-amz-error-message", equalTo("The specified key does not exist."))+ .body(emptyString());+ }++ @Test+ @Order(23)+ void websiteWithoutCustomErrorDocumentServesDefaultHtmlForGetAndHead() {+ String xml = """+ <WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">+ <IndexDocument>+ <Suffix>index.html</Suffix>+ </IndexDocument>+ </WebsiteConfiguration>+ """;+ given()+ .queryParam("website", "")+ .contentType("application/xml")+ .body(xml)+ .when()+ .put("/" + BUCKET)+ .then()+ .statusCode(200);++ var getResponse = given()+ .header("Host", websiteHost())+ .when()+ .get("/missing-page");++ getResponse.then()+ .statusCode(404)+ .contentType("text/html")+ .header("Content-Length", notNullValue())+ .header("x-amz-error-code", equalTo("NoSuchKey"))+ .header("x-amz-error-message", equalTo("The specified key does not exist."))+ .body(containsString("404 Not Found"))+ .body(containsString("NoSuchKey"));++ given()+ .header("Host", websiteHost())+ .when()+ .head("/missing-page")+ .then()+ .statusCode(404)+ .contentType("text/html")+ .header("Content-Length", equalTo(getResponse.header("Content-Length")))+ .header("x-amz-error-code", equalTo("NoSuchKey"))+ .header("x-amz-error-message", equalTo("The specified key does not exist."))+ .body(emptyString());+ }++ @Test+ @Order(24)void deleteWebsiteConfiguration() {given().queryParam("website", "")@@ -200,10 +428,12 @@ class S3WebsiteIntegrationTest {}@Test- @Order(13)+ @Order(25)void cleanup() {given().delete("/" + BUCKET + "/index.html");given().delete("/" + BUCKET + "/error.html");+ given().delete("/" + BUCKET + "/docs/index.html");+ given().delete("/" + BUCKET + "/a/b/index.html");given().delete("/" + BUCKET);}}