Document and/or standardize how ActionError and isActionError behave, so proxy servers can return predictable response errors.

[virtuallyunknown]

Body

Summary

Document and standardize the way ActionError and isActionError error behave, so that proxy servers sitting in front of an Astro server in SSR mode can create/throw predictable errors which can then be safely read on the client.

Background & Motivation

When an application is deployed behind a reverse-proxy such as NGINX, the proxy may return errors directly to the client (browser) in certain conditions. Common examples include caching, rate-limiting or request body size limits:

http {
    # ...

    limit_req_zone $binary_remote_addr zone=uploads:100m rate=25r/m;

    server {
        listen 443 ssl;

        # ...
        # intercept requests towards this astro action and apply rate/size limiting
        location ^~ /_actions/products.uploadImage {
            proxy_pass http://localhost:4321;
            proxy_http_version 1.1;

            client_max_body_size 25M;

            limit_req zone=uploads burst=5 nodelay;
            limit_req_status 429;
        }

        error_page 413 = @json_413;
        error_page 429 = @json_429;

        location @json_413 {
            default_type application/json;
            return 413 '{"error": "Request Entity Too Large"}';
        }

        location @json_429 {
            default_type application/json;
            return 429 '{"error": "Too Many Requests"}';
        }
    }
}

When an action is called on the frontend of our application, the proxy server will intercept the request. If the request is valid and it satisfies our file size and rate limit constraints, the proxy will forward it to our Astro server (the proxy_pass directive). But if the request fails, the proxy will bypass Astro server altogether and send a response with a status code, Content-Type: application/json headers and optionally some JSON payload directly to the client.

const { data, error } = await actions.products.uploadImage(formData);

If this request fails on a proxy level (when it bypasses Astro), we can still inspect the error object, but it's code and status will not match those that the proxy server sent.

console.log(JSON.stringify(error, null, 4));
// {
//     "type": "AstroActionError",
//     "code": "INTERNAL_SERVER_ERROR",
//     "status": 500
// }

So what do we do now? I studied the source code to discover how Astro creates these errors when actions are called on the frontend.

1. handleAction returns a deserializeActionResult with a type of error and more importantly for our use case, body: await rawResult.text().

2. deserializeActionResult tries to parse the body as json, and then returns { error: ActionError.fromJson(json), data: undefined };

3. fromJson is a static method of the ActionError class, which does a conditional check to see if the value passed isActionError, and if it is, it returns new a instance of ActionError(body).

So with all that information in hand, all we have to do in order to pass custom errors from our proxy server to our client, and allow them to be correctly interpreted by Astro, is to study how isActionError function works:

export function isActionError(error?: unknown): error is ActionError {
	return (
		typeof error === 'object' &&
		error != null &&
		'type' in error &&
		error.type === 'AstroActionError'
	);
}

We just need to return an object with a type of AstroActionError, and the code needs to match a key defined in codeToStatusMap

http {
    # ...
    server {
        # ...
        location @json_413 {
            default_type application/json;
            return 413 '{"type":"AstroActionError", "code":"CONTENT_TOO_LARGE"}';
        }

        location @json_429 {
            default_type application/json;
            return 429 '{"type":"AstroActionError", "code":"TOO_MANY_REQUESTS"}';
        }
    }
}

const { data, error } = await actions.products.uploadImage(formData);
console.log(JSON.stringify(error, null, 4));
// ✅
// {
//     "type": "AstroActionError",
//     "code": "CONTENT_TOO_LARGE",
//     "status": 413
// }

Goals

At the moment, the solution described above works, but none of this is standard or documented, and requires digging into source code, so there are no guarantees that the internal logic won't change and cause breakage between releases.

• Document and/or standardize how ActionError and isActionError error behaves so that developers who intend to use this in non-standard ways can do so in a predictable way.

I also realize this use case may be relatively niche, so it’s completely understandable if the Astro team chooses not to spend time on this. If that’s the case, I would still appreciate any insight into the intended direction moving forward, and whether this behavior might be considered (and listed as) a breaking change should the core logic be updated in the future.

Thank you!