Add configuration for deployment on two separate domains [server-islands]

[Jacob-Roberts]

Summary

Allow deployment on two separate domains using server islands to separate “public” (static) and “sensitive”(dynamic) aspects of a website.

Background & Motivation

Every website is a mix of public and private information. Traditionally, JS and CSS have been the only truly static content. However Astro Server islands can truly change this paradigm.

In the past, self-hosting a website that deals with sensitive information requires making a performance/trust tradeoff. You can either:

1. Host the entire website on your own trusted servers, but lose the ability to take advantage of CDNs for solid user experiences.
2. Use a cloud provider to host/cache data to have fast performance, but trust your users’ data with a 3rd party.

Astro’s new server islands feature presents a unique opportunity to provide a middle ground that eliminates many of the downsides and satisfies both the privacy and the security requirements.

This is of particular interest to the “homelabber” community who want to host websites on their own trusted infrastructure, but want to cache as many static assets as possible on a CDN.

I know a full JAM-stack website is possible where the HTML is fully cached, but thin. However, this requires too much of the app to be client rendered. Astro is a great tool that allows flexibility and selectivity on what is hydrated and in what method. I want to server render components, AND I want the rest of the app to be statically cached.
Anything that is static should come in the initial HTML response.

It is currently possible to almost accomplish this goal with the build.assetsPrefix directive, but this only supports accessing JS/CSS from a separate domain. If my origin server is still far from users, they still get a slow experience.

The truly best state would be if the initial page request (HTML document) was also cached in a CDN, and all dynamic (server islands) were accessed from the origin server.

Note

An important distinction here is that for the static assets, the CDN holds the TLS certificate, whereas for the connection to the origin server, I hold the TLS certificate

Goals

• Astro build supports hosting all static assets including all HTML from a separate domain from the dynamic server island domain
  • https://mysite.com (static HTML, CSS, JS [cache control headers])
  • https://api.mysite.com (server islands, API endpoints)
• These two URLs are configurable in astro.config.js
• Example deployment using two Dockerfiles showing a static file webserver and a dynamic Astro node container

Details

For this example, I’ll refer to mysite.com as the static domain and api.mysite.com as the dynamic domain.

For a simplified use case, assume that both mysite.com and api.mysite.com are both being hosted on a single machine behind a reverse proxy.

However, mysite.com is behind a cloudflare DNS proxy that has the CDN setup correctly, meaning that any response returned will be properly cached and propagated worldwide. Cloudflare holds the TLS certificates for encryption with the users browser.

api.mysite.com is not behind a proxy. Any requests to that domain will go directly to the origin server. I hold the TLS certificates for encryption with the users browser.

Implementation - runtime

To implement this at runtime, I’ve been able to accomplish this through tinkering with the dist folder of a v5 built application. It requires changing the /_server-islands/… URL to simply have a fully qualified URL like https://api.mysite.com/_server-islands/…

Implementation - build time

I have attempted to build this as a separate adapter so as to not clutter the @astro/node integration with extra configuration that is most likely not applicable to everyone.

However. After looking through the code it appears that the server island code is not adapter specific and resides in the core package, so this seems like it will require adding more extensibility to the core package to allow this to be integration specific.

This is particularly where I am looking for help.

CORS

Since we will be making cross origin requests, api.mysite.com needs to provide access control headers to allowlist mysite.com as a valid origin.

It seems that currently all requests are GET so they are simple CORS requests, but this may require more advanced CORS headers if server islands needs it.

Header	Value
Access-Control-Allow-Origin	https://mysite.com
Access-Control-Allow-Credentials	true
Vary	Origin
Access-Control-Expose-Headers	MyCustomHeaders

Encryption secret

Since we will have two separate servers, the encryption secret will need to be kept in sync. This can be accomplished with the ASTRO_KEY environment variable, but it’s important to keep in mind as this complicates the deployment.

Static file server vs node server

For my initial exploration, I used the same node server for both the "static file server" and the "dynamic server". This was merely for convenience, but it should be possible to either:

1. Directly upload the static assets to something like S3 and then properly handle the index.html files
2. Use something like cloudflare CDN that uses the cache headers on the default node server to determine how to cache things.

The specifics aren't important here, and are not part of this RFC.

Why not [insert here]?

Use a single domain and put it all behind Cloudflare Proxy?

If the entire app was hosted and proxied through cloudflare, we could rely on cache headers to control which parts of the HTML is cached.

This is true, however the key difference is that if it's all on a single domain, then Cloudflare holds the TLS certificate. For this use case, imagine that I am serving highly sensitive data that cannot be served through Cloudflare. The TLS certificate for sensitive (dynamic) data must be between the browser and the origin directly.

Just use assetsPrefix?

As stated above, I want the initial index.html to be as fast as possible. I know I can cache that and optimize for the second visit, but there's nothing intrinsically uncacheable about the static bits of the HTML. In theory, it should be cacheable because it's the same for all users. So even for the first user it should come from their closest CDN server rather than from the origin.

Thanks

Thank you for all your hard work! This project is amazing, and I'm happy to contribute any way I can here.

Note

This is written in relation to a homelab project I wrote about here, but this is not required reading, and is somewhat separate from this discussion.

[Jacob-Roberts]

Draft PR created withastro/astro#12320

More work needed

[apatel369]

This is really interesting feature. Thanks for detailed explanation. Is there anything left in draft PR besides e2e test?

[Jacob-Roberts]

I didn't add tests or docs because I wanted to gauge the teams interest/willingness to merge a feature to enable this.

If this seems like a valuable change, I'd be happy to write some docs and tests

[apatel369]

Besides separating public and private information, this feature can also be useful for marketing sites, blogs, and storefronts to render server islands closer to the data source, which improves performance. This is similar to Next.js PPR, which allows all static parts to be served from the edge while dynamic parts can be computed near the data source. I don't see a reason why we shouldn't add this. Were you able to build an adapter for this? I see you mentioned you need help with the build-time implementation.

[Jacob-Roberts]

Yeah, exactly! I was able to add an adapter for this, it's all available in this sample PR.

I closed that PR, as the code for this doesn't need to be built directly into the astro code repo. Unless that's desirable.

There are two pieces needed to make it work:

1. Changes to the astro core to make the URL configurable by adapters
2. The adapter itself.

Part 1 is available in this PR

And part 2 I can write after the core is merged

[apatel369]

Since you only have tests and documentation remaining, please add these and make the PR ready for review. This way, you will receive feedback faster I think.

[Jacob-Roberts]

Ok, since you're in favor of the PR, I'll add all the necessary pieces to get it ready for review. Thanks for the feedback!

[Jacob-Roberts]

I've updated the PR with a test.

Haven't done docs yet, but that's in a separate repo anyway. I can do that first, or as a subsequent PR, whatever is best.

[Jacob-Roberts]

PR and Docs PR ready for review!

[ematipico]

Sometimes you speak about API endpoints, but then focus on server islands.

Those are both different features, so the proposal is for both or just server islands?

[Jacob-Roberts]

Both!

[Jacob-Roberts]

However, from my research, it seems like nothing in astro automatically "fills in the" base URL for API endpoints, so if someone wanted to use a dynamic-static split, they could manually control the API endpoint base URL.

The reason this focuses on server islands is that there is no way by default to control the base URL.

[matthewp]

Yeah, I don't think there's anything that Astro does to add links to endpoints, so it's on your app to provide that.

Another similar thing though is Astro Actions, where we do wrap fetch, set a form action, etc.

It would be much easier to accept this proposal if it applied to all server routes. Otherwise there would be a need to split out the build for special features and that would be quite difficult.

We have build.assetsPrefix already for scripts/styles, etc. so I could see a similar kind of config value like build.serverRoutePrefix (bikeshed) or something.