create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/middleware/builtin/cache.md

@@ -0,0 +1,122 @@
+# Cache Middleware
+
+> **Not yet available.** The cache middleware (`acrylblends/cache`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+The Cache middleware uses the Web Standards' [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+
+The Cache middleware currently supports Cloudflare Workers projects using custom domains and Deno projects using [Deno 1.26+](https://github.com/denoland/deno/releases/tag/v1.26.0). Also available with Deno Deploy.
+
+Cloudflare Workers respects the `Cache-Control` header and return cached responses. For details, refer to [Cache on Cloudflare Docs](https://developers.cloudflare.com/workers/runtime-apis/cache/). Deno does not respect headers, so if you need to update the cache, you will need to implement your own mechanism.
+
+See [Usage](#usage) below for instructions on each platform.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { cache } from 'acrylblends/cache'
+```
+
+## Usage
+
+**Cloudflare Workers**
+
+```ts
+app.get(
+  '*',
+  cache({
+    cacheName: 'my-app',
+    cacheControl: 'max-age=3600',
+  })
+)
+```
+
+**Deno**
+
+```ts
+// Must use `wait: true` for the Deno runtime
+app.get(
+  '*',
+  cache({
+    cacheName: 'my-app',
+    cacheControl: 'max-age=3600',
+    wait: true,
+  })
+)
+```
+
+## Caching QUERY requests
+
+The Cache middleware also caches responses to [QUERY](https://www.rfc-editor.org/rfc/rfc10008.html) requests. As required by RFC 10008, the cache key for a QUERY request incorporates a digest of the request content and its representation metadata, so requests with different bodies are cached separately.
+
+QUERY requests with a body larger than `maxQueryBodySize` (64 KiB by default) bypass the cache.
+
+> **Note.** To support this, cached entries are stored under an internal key, so they do not collide with your own requests.
+
+## Options
+
+### **(required)** cacheName: `string` | `(c: Context) => string` | `Promise<string>`
+
+The name of the cache. Can be used to store multiple caches with different identifiers.
+
+### *(optional)* wait: `boolean`
+
+A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request. _Required to be true for the Deno environment_. The default is `false`.
+
+### *(optional)* cacheControl: `string`
+
+A string of directives for the `Cache-Control` header. See the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for more information. When this option is not provided, no `Cache-Control` header is added to requests.
+
+### *(optional)* vary: `string` | `string[]`
+
+Sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates. Setting this to `*` will result in an error. For more details on the Vary header and its implications for caching strategies, refer to the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary).
+
+### *(optional)* keyGenerator: `(c: Context) => string | Promise<string>`
+
+Generates keys for every request in the `cacheName` store. This can be used to cache data based on request parameters or context parameters. The default is `c.req.url`. For QUERY requests, the key additionally includes a digest of the request content and its representation metadata.
+
+### *(optional)* maxQueryBodySize: `number`
+
+The maximum QUERY request body size in bytes that can be cached. QUERY requests with a larger body bypass the cache. The default is `65536` (64 KiB).
+
+### *(optional)* cacheableStatusCodes: `number[]`
+
+An array of status codes that should be cached. The default is `[200]`. Use this option to cache responses with specific status codes.
+
+```ts
+app.get(
+  '*',
+  cache({
+    cacheName: 'my-app',
+    cacheControl: 'max-age=3600',
+    cacheableStatusCodes: [200, 404, 412],
+  })
+)
+```
+
+### *(optional)* onCacheNotAvailable: `((reason: string) => void | Promise<void>)` | `false`
+
+A callback function or `false` that controls the behavior when the Cache API is not available in the global scope, or when QUERY caching cannot use Web Crypto. The callback is invoked with the reason. By default, the reason is logged with `console.log`. You can provide a custom function to customize the behavior, or set it to `false` to suppress the log entirely.
+
+```ts
+// Custom logging
+app.use(
+  cache({
+    cacheName: 'my-app-v1',
+    onCacheNotAvailable: () => {
+      console.log('Custom log: Cache API is not available.')
+    },
+  })
+)
+```
+
+```ts
+// Suppress logging
+app.use(
+  cache({
+    cacheName: 'my-app-v1',
+    onCacheNotAvailable: false,
+  })
+)
+```

package/docs/framework/middleware/builtin/combine.md

@@ -0,0 +1,94 @@
+# Combine Middleware
+
+Combine Middleware combines multiple middleware functions into a single middleware. It provides three functions:
+
+- `some` - Runs only one of the given middleware.
+- `every` - Runs all given middleware.
+- `except` - Runs all given middleware only if a condition is not met.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { some, every, except } from 'acrylblends/combine'
+```
+
+## Usage
+
+Here's an example of complex access control rules using Combine Middleware.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+import { getConnInfo } from 'acrylblends/node-server'
+import { every, some } from 'acrylblends/combine'
+import { ipRestriction } from 'acrylblends/ip-restriction'
+import { rateLimit } from '@/my-rate-limit'
+
+const app = new Acryl()
+
+app.use(
+  '*',
+  some(
+    every(
+      ipRestriction(getConnInfo, { allowList: ['192.168.0.2'] }),
+      bearerAuth({ token })
+    ),
+    // If both conditions are met, rateLimit will not execute.
+    rateLimit()
+  )
+)
+
+app.get('/', (c) => c.text('Hello Acryl!'))
+```
+
+### some
+
+Runs the first middleware that returns true. Middleware is applied in order, and if any middleware exits successfully, subsequent middleware will not run.
+
+```ts
+import { some } from 'acrylblends/combine'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+import { myRateLimit } from '@/rate-limit'
+
+// If client has a valid token, skip rate limiting.
+// Otherwise, apply rate limiting.
+app.use(
+  '/api/*',
+  some(bearerAuth({ token }), myRateLimit({ limit: 100 }))
+)
+```
+
+### every
+
+Runs all middleware and stops if any of them fail. Middleware is applied in order, and if any middleware throws an error, subsequent middleware will not run.
+
+```ts
+import { some, every } from 'acrylblends/combine'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+import { myCheckLocalNetwork } from '@/check-local-network'
+import { myRateLimit } from '@/rate-limit'
+
+// If client is in local network, skip authentication and rate limiting.
+// Otherwise, apply authentication and rate limiting.
+app.use(
+  '/api/*',
+  some(
+    myCheckLocalNetwork(),
+    every(bearerAuth({ token }), myRateLimit({ limit: 100 }))
+  )
+)
+```
+
+### except
+
+Runs all middleware except when the condition is met. You can pass a string or function as the condition. If multiple targets need to be matched, pass them as an array.
+
+```ts
+import { except } from 'acrylblends/combine'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+
+// If client is accessing public API, skip authentication.
+// Otherwise, require a valid token.
+app.use('/api/*', except('/api/public/*', bearerAuth({ token })))
+```

package/docs/framework/middleware/builtin/compress.md

@@ -0,0 +1,59 @@
+# Compress Middleware
+
+This middleware compresses the response body, according to `Accept-Encoding` request header.
+
+> **Note.** On Cloudflare Workers and Deno Deploy, the response body will be compressed automatically, so there is no need to use this middleware.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { compress } from 'acrylblends/compress'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(compress())
+```
+
+## Options
+
+### *(optional)* encoding: `'gzip'` | `'deflate'`
+
+The compression scheme to allow for response compression. Either `gzip` or `deflate`. If not defined, both are allowed and will be used based on the `Accept-Encoding` header. `gzip` is prioritized if this option is not provided and the client provides both in the `Accept-Encoding` header.
+
+### *(optional)* threshold: `number`
+
+The minimum size in bytes to compress. Defaults to 1024 bytes.
+
+### *(optional)* contentTypeFilter: `RegExp` | `(contentType: string) => boolean`
+
+A `RegExp` or function to determine whether the response should be compressed based on its `Content-Type`. By default, a built-in list of compressible Content-Types is used.
+
+You can pass a `RegExp` to compress only matching Content-Types:
+
+```ts
+// Compress only JSON responses
+app.use(compress({ contentTypeFilter: /^application\/json/ }))
+```
+
+Or pass a function for custom logic. The built-in `COMPRESSIBLE_CONTENT_TYPE_REGEX` is also exported so you can extend the default behavior:
+
+```ts
+import {
+  compress,
+  COMPRESSIBLE_CONTENT_TYPE_REGEX,
+} from 'acrylblends/compress'
+
+// Compress the default Content-Types plus a custom one
+app.use(
+  compress({
+    contentTypeFilter: (type) =>
+      COMPRESSIBLE_CONTENT_TYPE_REGEX.test(type) ||
+      type === 'application/x-myformat',
+  })
+)
+```

package/docs/framework/middleware/builtin/context-storage.md

@@ -0,0 +1,78 @@
+# Context Storage Middleware
+
+The Context Storage Middleware stores the Acryl `Context` in the `AsyncLocalStorage`, to make it globally accessible.
+
+> **Note.** This middleware uses `AsyncLocalStorage`. The runtime should support it.
+>
+> **Cloudflare Workers**: To enable `AsyncLocalStorage`, add the [`nodejs_compat` or `nodejs_als` flag](https://developers.cloudflare.com/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml` file.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import {
+  contextStorage,
+  getContext,
+  tryGetContext,
+} from 'acrylblends/context-storage'
+```
+
+## Usage
+
+The `getContext()` will return the current Context object if the `contextStorage()` is applied as a middleware.
+
+```ts
+type Env = {
+  Variables: {
+    message: string
+  }
+}
+
+const app = new Acryl<Env>()
+
+app.use(contextStorage())
+
+app.use(async (c, next) => {
+  c.set('message', 'Hello!')
+  await next()
+})
+
+// You can access the variable outside the handler.
+const getMessage = () => {
+  return getContext<Env>().var.message
+}
+
+app.get('/', (c) => {
+  return c.text(getMessage())
+})
+```
+
+On Cloudflare Workers, you can access the bindings outside the handler.
+
+```ts
+type Env = {
+  Bindings: {
+    KV: KVNamespace
+  }
+}
+
+const app = new Acryl<Env>()
+
+app.use(contextStorage())
+
+const setKV = (value: string) => {
+  return getContext<Env>().env.KV.put('key', value)
+}
+```
+
+## tryGetContext
+
+`tryGetContext()` works like `getContext()`, but returns `undefined` instead of throwing an error when the context is not available:
+
+```ts
+const context = tryGetContext<Env>()
+if (context) {
+  // Context is available
+  console.log(context.var.message)
+}
+```

package/docs/framework/middleware/builtin/cors.md

@@ -0,0 +1,135 @@
+# CORS Middleware
+
+There are many use cases of Cloudflare Workers as Web APIs and calling them from external front-end application.
+For them we have to implement CORS, let's do this with middleware as well.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { cors } from 'acrylblends/cors'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+// CORS should be called before the route
+app.use('/api/*', cors())
+app.use(
+  '/api2/*',
+  cors({
+    origin: 'http://example.com',
+    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
+    allowMethods: ['POST', 'GET', 'OPTIONS'],
+    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
+    maxAge: 600,
+    credentials: true,
+  })
+)
+
+app.all('/api/abc', (c) => {
+  return c.json({ success: true })
+})
+app.all('/api2/abc', (c) => {
+  return c.json({ success: true })
+})
+```
+
+Multiple origins:
+
+```ts
+app.use(
+  '/api3/*',
+  cors({
+    origin: ['https://example.com', 'https://example.org'],
+  })
+)
+
+// Or you can use "function"
+app.use(
+  '/api4/*',
+  cors({
+    // `c` is a `Context` object
+    origin: (origin, c) => {
+      return origin.endsWith('.example.com')
+        ? origin
+        : 'http://example.com'
+    },
+  })
+)
+```
+
+Dynamic allowed methods based on origin:
+
+```ts
+app.use(
+  '/api5/*',
+  cors({
+    origin: (origin) =>
+      origin === 'https://example.com' ? origin : '*',
+    // `c` is a `Context` object
+    allowMethods: (origin, c) =>
+      origin === 'https://example.com'
+        ? ['GET', 'HEAD', 'POST', 'PATCH', 'DELETE']
+        : ['GET', 'HEAD'],
+  })
+)
+```
+
+## Options
+
+### *(optional)* origin: `string` | `string[]` | `(origin:string, c:Context) => string`
+
+The value of "_Access-Control-Allow-Origin_" CORS header. You can also pass the callback function like `origin: (origin) => (origin.endsWith('.example.com') ? origin : 'http://example.com')`. The default is `*`.
+
+### *(optional)* allowMethods: `string[]` | `(origin:string, c:Context) => string[]`
+
+The value of "_Access-Control-Allow-Methods_" CORS header. You can also pass a callback function to dynamically determine allowed methods based on the origin. The default is `['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH', 'QUERY']`.
+
+### *(optional)* allowHeaders: `string[]`
+
+The value of "_Access-Control-Allow-Headers_" CORS header. The default is `[]`.
+
+### *(optional)* maxAge: `number`
+
+The value of "_Access-Control-Max-Age_" CORS header.
+
+### *(optional)* credentials: `boolean`
+
+The value of "_Access-Control-Allow-Credentials_" CORS header.
+
+### *(optional)* exposeHeaders: `string[]`
+
+The value of "_Access-Control-Expose-Headers_" CORS header. The default is `[]`.
+
+## Environment-dependent CORS configuration
+
+If you want to adjust CORS configuration according to the execution environment, such as development or production, injecting values from environment variables is convenient as it eliminates the need for the application to be aware of its own execution environment. See the example below for clarification.
+
+```ts
+app.use('*', async (c, next) => {
+  const corsMiddlewareHandler = cors({
+    origin: c.env.CORS_ORIGIN,
+  })
+  return corsMiddlewareHandler(c, next)
+})
+```
+
+## Using with Vite
+
+When using Acryl with Vite, you should disable Vite's built-in CORS feature by setting `server.cors` to `false` in your `vite.config.ts`. This prevents conflicts with Acryl's CORS middleware.
+
+```ts
+// vite.config.ts
+import { cloudflare } from '@cloudflare/vite-plugin'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    cors: false, // disable Vite's built-in CORS setting
+  },
+  plugins: [cloudflare()],
+})
+```

package/docs/framework/middleware/builtin/csrf.md

@@ -0,0 +1,105 @@
+# CSRF Protection
+
+This middleware protects against CSRF attacks by checking both the `Origin` header and the `Sec-Fetch-Site` header. The request is allowed if either validation passes.
+
+The middleware only validates requests that:
+
+- Use unsafe HTTP methods (not GET, HEAD, or OPTIONS)
+- Have content types that can be sent by HTML forms (`application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain`)
+
+Old browsers that do not send `Origin` headers, or environments that use reverse proxies to remove these headers, may not work well. In such environments, use other CSRF token methods.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { csrf } from 'acrylblends/csrf'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+// Default: both origin and sec-fetch-site validation
+app.use(csrf())
+
+// Allow specific origins
+app.use(csrf({ origin: 'https://myapp.example.com' }))
+
+// Allow multiple origins
+app.use(
+  csrf({
+    origin: [
+      'https://myapp.example.com',
+      'https://development.myapp.example.com',
+    ],
+  })
+)
+
+// Allow specific sec-fetch-site values
+app.use(csrf({ secFetchSite: 'same-origin' }))
+app.use(csrf({ secFetchSite: ['same-origin', 'none'] }))
+
+// Dynamic origin validation
+// It is strongly recommended that the protocol be verified to ensure a match to `$`.
+// You should *never* do a forward match.
+app.use(
+  '*',
+  csrf({
+    origin: (origin) =>
+      /https:\/\/(\w+\.)?myapp\.example\.com$/.test(origin),
+  })
+)
+
+// Dynamic sec-fetch-site validation
+app.use(
+  csrf({
+    secFetchSite: (secFetchSite, c) => {
+      // Always allow same-origin
+      if (secFetchSite === 'same-origin') return true
+      // Allow cross-site for webhook endpoints
+      if (
+        secFetchSite === 'cross-site' &&
+        c.req.path.startsWith('/webhook/')
+      ) {
+        return true
+      }
+      return false
+    },
+  })
+)
+```
+
+## Options
+
+### *(optional)* origin: `string` | `string[]` | `Function`
+
+Specify allowed origins for CSRF protection.
+
+- **`string`**: Single allowed origin (e.g., `'https://example.com'`)
+- **`string[]`**: Array of allowed origins
+- **`Function`**: Custom handler `(origin: string, context: Context) => boolean` for flexible origin validation and bypass logic
+
+**Default**: Only same origin as the request URL
+
+The function handler receives the request's `Origin` header value and the request context, allowing for dynamic validation based on request properties like path, headers, or other context data.
+
+### *(optional)* secFetchSite: `string` | `string[]` | `Function`
+
+Specify allowed Sec-Fetch-Site header values for CSRF protection using [Fetch Metadata](https://web.dev/articles/fetch-metadata).
+
+- **`string`**: Single allowed value (e.g., `'same-origin'`)
+- **`string[]`**: Array of allowed values (e.g., `['same-origin', 'none']`)
+- **`Function`**: Custom handler `(secFetchSite: string, context: Context) => boolean` for flexible validation
+
+**Default**: Only allows `'same-origin'`
+
+Standard Sec-Fetch-Site values:
+
+- `same-origin`: Request from same origin
+- `same-site`: Request from same site (different subdomain)
+- `cross-site`: Request from different site
+- `none`: Request not from a web page (e.g., browser address bar, bookmark)
+
+The function handler receives the request's `Sec-Fetch-Site` header value and the request context, enabling dynamic validation based on request properties.

package/docs/framework/middleware/builtin/etag.md

@@ -0,0 +1,54 @@
+# ETag Middleware
+
+Using this middleware, you can add ETag headers easily.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { etag } from 'acrylblends/etag'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use('/etag/*', etag())
+app.get('/etag/abc', (c) => {
+  return c.text('Acryl is cool')
+})
+```
+
+## The retained headers
+
+The 304 Response must include the headers that would have been sent in an equivalent 200 OK response. The default headers are Cache-Control, Content-Location, Date, ETag, Expires, and Vary.
+
+If you want to add the header that is sent, you can use `retainedHeaders` option and `RETAINED_304_HEADERS` strings array variable that includes the default headers:
+
+```ts
+import { etag, RETAINED_304_HEADERS } from 'acrylblends/etag'
+
+// ...
+
+app.use(
+  '/etag/*',
+  etag({
+    retainedHeaders: ['x-message', ...RETAINED_304_HEADERS],
+  })
+)
+```
+
+## Options
+
+### *(optional)* weak: `boolean`
+
+Define using or not using a [weak validation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests#weak_validation). If `true` is set, then `w/` is added to the prefix of the value. The default is `false`.
+
+### *(optional)* retainedHeaders: `string[]`
+
+The headers that you want to retain in the 304 Response.
+
+### *(optional)* generateDigest: `(body: Uint8Array) => ArrayBuffer | Promise<ArrayBuffer>`
+
+A custom digest generation function. By default, it uses `SHA-1`. This function is called with the response body as a `Uint8Array` and should return a hash as an `ArrayBuffer` or a Promise of one.