Environment API + Cloudflare plugin plan

[ascorbic]

Environment API + Cloudflare plugin plan

The goal of this project is to support running dev rendering in a separate Vite environment. This should allow adapter-specific entrypoints, including user-specified entrypoints if supported by the adapter.

The Vite docs include a guide to the Environment API for frameworks that is very helpful to read alongside this

Architecture

It looks like the best approach is to use the SSR App class in dev, replacing the current way that requests are handled in vite-plugin-astro-server. This will help us keep a separation of concerns between Vite and the actual rendering, and allow adapters to provide custom entrypoints. Currently the Astro dev middleware directly handles requests, with much of the logic inside the plugin itself. This is for historic reasons, because it was created before SSR was implemented, which when the App class was created, abstracting request handling for SSR. We will need to create a way to allow App to run in dev, which will effectively be a complete rewrite of the dev server.

We would create a default dev environment and entrypoint that runs NodeApp (or some other App type). Adapters could optionally use a Vite plugin to register their own environment for dev that could use a different entrypoint and/or runtime. The simplest approach here would be to require them to create a FetchableDevEnvironment, which would allow us to create a Request that we dispatch to the environment, which can handle it as it sees fit. Cloudflare could take the request and dispatch it to miniflare, for example. This unfortunately isn't what Cloudflare does (see below for details), but there are ways we can work around this

graph TB
    subgraph "Vite Dev Server"
        A[User Request] -->|Node IncomingMessage| B
        
        subgraph "Astro dev middleware"
            B[Convert req to Request Object]
            B -->|dispatchFetch| C{Dispatch to SSR Environment}
            F[Response from SSR] --> G[Write Response to res]
        end
        
        G -->|Node ServerResponse| H[Return to User]
    end
    
    subgraph "SSR Environment"
        C -->|Request| D[Load Entrypoint]
        D --> E[Handle Request & Generate Response]
        E -->|Response| F
    end

Loading

The main issue with this is that App (and NodeApp) rely on a lot of artifacts that are generated during the build, and virtual modules that are only available in the build. Some of these can be re-implemented in dev, but it is likely that this will be where many of the issues will occur.

SSR Manifest

An SSR adapter exports an entrypoint using createExports, which is passed an SSRManifest in Astro's generated entrypoint. The entrypoint passes the manifest to the App contructor. This manifest includes everything that the server needs to handle a response, including details of config, routes, renderers, as well as dynamic imports to load the actual page components. This manifest is imported from a virtual module astro:ssr-manifest, that is generated by a Vite plugin, which is in turn injected by an Astro plugin that handles generating and serialising the manifest.

In our new world, the entrypoint will need to be able to import the manifest using the virtual module in both dev and production. Currently we use an internal manifest plugin that handles the virtual module in build. It loads the serialised manifest data from disk, and then deserialises, including adding things such as dynamic imports of session adapters and page modules.

Currently in dev, the manifest is handled differently, and is not registered as a module but rather passed to the pipeline directly. We would need to do an of the build handling to allow the virtual module to work in dev too. This would force us to ensure that they don't rely on being in the same process.

Cloudflare plugin architecture

Cloudflare has recently published @cloudflare/vite-plugin, which handles most of what is needed to run the Vite dev server within a workerd environment. It does this with a custom dev environment that passes requests to the locally-configured worker entrypoint, running in miniflare. As I touched on above, this environment doesn't implement the dispatchFetch method, which would simplify things. Instead it takes full control of dev rendering by adding middleware to the dev server that intercepts requests and handles the dispatch of these to the dev environment. I have asked if they will implement a FetchableDevEnvironment which would make it easier to adopt a standardised approach to environments. In the interim, we can skip our own request handling by detecting if the response has already started to be sent, indicating that some other middleware has already started to process it, and assume that this is Cloudflare doing its own thing.

[ematipico]

Currently in dev, the manifest is handled differently, and is not registered as a module but rather passed to the pipeline directly. We would need to do an the build handling to allow the virtual module to work in dev too. This would force us to ensure that they don't rely on being in the same process.

That's a tough one, at the moment the manifest of the dev pipeline is filled with almost no information, because we don't have it. Few examples: middleware and actions. However, maybe we might be able to fix it by importing their virtual modules directly

[ascorbic]

Yeah, it doesn't even include routes right now. Presumably for most of the missing parts, the information is available once we handle the requests, even if it's not available in the context where we're generating the manifest.