WC-2955 Add documentation for serve_directly usage

Author: WillTaylorDev

src/content/docs/workers/static-assets/binding.mdx

@@ -17,6 +17,8 @@ import {
 	Tabs,
 } from "~/components";
 
+import { WranglerConfig } from "~/components";
+
 Configuring a Worker with assets requires specifying a [directory](/workers/static-assets/binding/#directory) and, optionally, an [assets binding](/workers/static-assets/binding/), in your Worker's `wrangler.toml` file. The [assets binding](/workers/static-assets/binding/) allows you to dynamically fetch assets from within your Worker script (e.g. `env.ASSETS.fetch()`), similarly to how you might with a make a `fetch()` call with a [Service binding](/workers/runtime-apis/bindings/service-bindings/http/).
 
 Only one collection of static assets can be configured in each Worker.
@@ -25,8 +27,6 @@ Only one collection of static assets can be configured in each Worker.
 
 The folder of static assets to be served. For many frameworks, this is the `./public/`, `./dist/`, or `./build/` folder.
 
-import { WranglerConfig } from "~/components";
-
 <WranglerConfig>
 
 ```toml title="wrangler.toml"
@@ -37,11 +37,26 @@ assets = { directory = "./public/" }
 
 </WranglerConfig>
 
-## `binding`
+## `serve_directly`
 
-Configuring the optional [binding](/workers/runtime-apis/bindings) gives you access to the collection of assets from within your Worker script.
+Controls whether assets will be served first on a matching request. `serve_directly = true` ([default](/workers/static-assets/routing/#default-behavior)) will serve any static asset matching a request, while `serve_directly = false` will unconditionally [invoke your Worker script](/workers/static-assets/routing/#invoking-worker-script-ahead-of-assets).
 
+<WranglerConfig>
 
+```toml title="wrangler.toml"
+name = "my-worker"
+compatibility_date = "2024-09-19"
+main = "src/index.ts"
+ # The following configuration unconditionally invokes the Worker script at
+ # `src/index.ts`, which can programatically fetch assets via the ASSETS binding
+assets = { directory = "./public/", binding = "ASSETS", serve_directly = false }
+```
+
+</WranglerConfig>
+
+## `binding`
+
+Configuring the optional [binding](/workers/runtime-apis/bindings) gives you access to the collection of assets from within your Worker script.
 
 <WranglerConfig>
 

src/content/docs/workers/static-assets/compatibility-matrix.mdx

@@ -85,7 +85,7 @@ We plan to bridge the gaps between Workers and Pages and provide ways to migrate
 
 [^2]: Similar to <sup>3</sup>, to customize the HTTP headers that are returned by static assets, you can use [Service bindings](/workers/runtime-apis/bindings/service-bindings/) to connect a Worker in front of the Worker with assets.
 
-[^3]: If you need to run a Worker before serving static assets, you can create a separate Worker that acts as middleware, and then use [Service bindings](/workers/runtime-apis/bindings/service-bindings/) to forward the request to the Worker with assets. We plan to explore additional configuration to support more complex routing in the future.
+[^3]: Middleware can be configured via the `[serve_directly](/workers/static-assets/binding/#serve_directly)` option, but is charged as a normal Worker invocation. We plan to explore options for free middleware in the future.
 
 [^4]: You can handle redirects by adding code to your Worker (a [community package](https://npmjs.com/package/redirects-in-workers) is available for `_redirects` support), or you can use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/).
 

src/content/docs/workers/static-assets/routing.mdx

@@ -17,7 +17,11 @@ import {
 	Tabs,
 } from "~/components";
 
-Assets are served by attempting to match up the incoming request's pathname to a static asset. The structure and organization of files in your static asset directory, along with any routing configuration, determine the routing paths for your application. When a request invokes a Worker with assets:
+import { WranglerConfig } from "~/components";
+
+## Default behavior
+
+By default, assets are served by attempting to match up the incoming request's pathname to a static asset. The structure and organization of files in your static asset directory, along with any routing configuration, determine the routing paths for your application. When a request invokes a Worker with assets:
 
 1. If a request is found with a matching path to the current route requested then that asset will always be served.
 
@@ -33,6 +37,62 @@ In this example, request to `example.com/api` doesn't match a static asset so th
 
 ![A request to `example.com/blog` runs the Worker.](~/assets/images/workers/platform/assets/workers-assets-invoke-worker.png)
 
+## Invoking Worker Script Ahead of Assets
+
+Users may desire to run code before assets are served, much like [middleware in Pages](/pages/functions/middleware/). [`serve_directly`](/workers/static-assets/binding/#serve_directly) is provided as a configuration within wrangler.toml. When disabled, this option forces a user script to be invoked regardless of a request matching an asset.
+
+Take the following directory structure, wrangler.toml, and user Worker code:
+
+<FileTree>
+
+- wrangler.toml
+- package.json
+- public
+  - supersecret.txt
+- src
+  - index.ts
+
+</FileTree>
+
+<WranglerConfig>
+
+```toml title="wrangler.toml"
+name = "my-worker"
+compatibility_date = "2024-09-19"
+main = "src/index.ts"
+assets = { directory = "./public/", binding = "ASSETS", serve_directly = false }
+```
+
+</WranglerConfig>
+
+```js
+export default {
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === "/supersecret.txt") {
+      const auth = request.headers.get("Authorization");
+      if (!auth) {
+        return new Response("Forbidden", {
+          status: 403,
+          statusText: "Forbidden",
+          headers: {
+            "Content-Type": "text/plain",
+          },
+        });
+      }
+    }
+
+    return await env.ASSETS.fetch(request);
+  },
+};
+```
+
+In this example, any request will be routed to our user Worker, due to `serve_directly` being disabled. As a result, any request being made `/supersecret.txt` without an `Authorization` header will result in a 403.
+
 ## Routing configuration
 
 There are two options for asset serving that can be [configured in `wrangler.toml`](/workers/wrangler/configuration/#assets):
@@ -61,11 +121,13 @@ If you have custom 404 HTML pages, and configure `not_found_handling` to `"404-p
 
 Take the following directory structure:
 
-```
-|---- file.html
-|---- folder
-      |___ index.html
-```
+<FileTree>
+
+- file.html
+- folder
+  - index.html
+
+</FileTree>
 
 Based on the incoming requests, the following assets would be served:
 
@@ -99,8 +161,6 @@ Alternate configuration options are outlined on this page and can be specified i
 
 Example `wrangler.toml` configuration:
 
-import { WranglerConfig } from "~/components";
-
 <WranglerConfig>
 
 ```toml title="wrangler.toml"
@@ -113,11 +173,13 @@ assets = { directory = "./public", binding = "ASSETS", html_handling = "force-tr
 
 Take the following directory structure:
 
-```
-|---- file.html
-|---- folder
-      |___ index.html
-```
+<FileTree>
+
+- file.html
+- folder
+  - index.html
+
+</FileTree>
 
 **`html_handling: "auto-trailing-slash"`**
 
@@ -191,12 +253,14 @@ Based on the incoming requests, the following assets would be served:
 
 Take the following directory structure:
 
-```
-|---- 404.html
-|---- index.html
-|---- folder
-      |___ 404.html
-```
+<FileTree>
+
+- 404.html
+- index.html
+- folder
+  - 404.html
+
+</FileTree>
 
 **`not_found_handling: "none"`**
 

src/content/docs/workers/wrangler/configuration.mdx

@@ -981,6 +981,10 @@ The following options are available under the `assets` key.
 
   - The binding name used to refer to the assets. Optional, and only useful when a Worker script is set with `main`.
 
+- `serve_directly` <Type text="boolean" /> <MetaInfo text="optional, defaults to true" />
+
+  - Controls whether static assets are fetched directly, or a Worker script is invoked. Learn more about fetching assets when using [`serve_directly`](/workers/static-assets/routing/#invoking-worker-script-ahead-of-assets).
+
 - `html_handling`: <Type text={'"auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"'} /> <MetaInfo text={'optional, defaults to "auto-trailing-slash"'} />
 
   - Determines the redirects and rewrites of requests for HTML content. Learn more about the various options in [assets routing](/workers/static-assets/routing/#html_handling).