create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/helpers/testing.md

@@ -0,0 +1,101 @@
+# Testing Helper
+
+The Testing Helper provides functions to make testing of Acryl applications easier.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { testClient } from 'acrylblends/testing'
+```
+
+## `testClient()`
+
+The `testClient()` function takes an instance of Acryl as its first argument and returns an object typed according to your Acryl application's routes, similar to the [Acryl Client](../guides/rpc.md#client). This allows you to call your defined routes in a type-safe manner with editor autocompletion within your tests.
+
+**Important Note on Type Inference:**
+
+For the `testClient` to correctly infer the types of your routes and provide autocompletion, **you must define your routes using chained methods directly on the `Acryl` instance**.
+
+The type inference relies on the type flowing through the chained `.get()`, `.post()`, etc., calls. If you define routes separately after creating the Acryl instance (like the common pattern shown in the "Hello World" example: `const app = new Acryl(); app.get(...)`), the `testClient` will not have the necessary type information for specific routes, and you won't get the type-safe client features.
+
+**Example:**
+
+This example works because the `.get()` method is chained directly onto the `new Acryl()` call:
+
+```ts
+// index.ts
+const app = new Acryl().get('/search', (c) => {
+  const query = c.req.query('q')
+  return c.json({ query: query, results: ['result1', 'result2'] })
+})
+
+export default app
+```
+
+```ts
+// index.test.ts
+import { Acryl } from 'acrylblends'
+import { testClient } from 'acrylblends/testing'
+import { describe, it, expect } from 'vitest' // Or your preferred test runner
+import app from './app'
+
+describe('Search Endpoint', () => {
+  // Create the test client from the app instance
+  const client = testClient(app)
+
+  it('should return search results', async () => {
+    // Call the endpoint using the typed client
+    // Notice the type safety for query parameters (if defined in the route)
+    // and the direct access via .$get()
+    const res = await client.search.$get({
+      query: { q: 'acrylblends' },
+    })
+
+    // Assertions
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({
+      query: 'acrylblends',
+      results: ['result1', 'result2'],
+    })
+  })
+})
+```
+
+To include headers in your test, pass them as the second parameter in the call. The second parameter can also take an `init` property as a `RequestInit` object, allowing you to set headers, method, body, etc. Learn more about the `init` property [here](../guides/rpc.md#init-option).
+
+```ts
+// index.test.ts
+import { Acryl } from 'acrylblends'
+import { testClient } from 'acrylblends/testing'
+import { describe, it, expect } from 'vitest' // Or your preferred test runner
+import app from './app'
+
+describe('Search Endpoint', () => {
+  // Create the test client from the app instance
+  const client = testClient(app)
+
+  it('should return search results', async () => {
+    // Include the token in the headers and set the content type
+    const token = process.env.API_TOKEN!
+    const res = await client.search.$get(
+      {
+        query: { q: 'acrylblends' },
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': `application/json`,
+        },
+      }
+    )
+
+    // Assertions
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({
+      query: 'acrylblends',
+      results: ['result1', 'result2'],
+    })
+  })
+})
+```

package/docs/framework/helpers/websocket.md

@@ -0,0 +1,215 @@
+# WebSocket Helper
+
+WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
+The Node.js adapter is available; the others are not yet available.
+
+## Import
+
+Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
+
+**Cloudflare Workers**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { upgradeWebSocket } from 'acrylblends/cloudflare-workers'
+```
+
+**Bun**
+
+```ts
+import { Acryl } from 'acrylblends'
+import { upgradeWebSocket, websocket } from 'acrylblends/bun'
+
+// ...
+
+export default {
+  fetch: app.fetch,
+  websocket,
+}
+```
+
+**Node.js**
+
+```ts
+import { serve, upgradeWebSocket } from 'acrylblends/node-server'
+import { Acryl } from 'acrylblends'
+import { WebSocketServer } from 'ws'
+```
+
+On Node.js, WebSocket support is built into `acrylblends/node-server`. To enable it, install `ws` and, if you use TypeScript, `@types/ws`. Then create a `WebSocketServer` with `{ noServer: true }` and pass it to `serve()` via the `websocket` option.
+
+## `upgradeWebSocket()`
+
+`upgradeWebSocket()` returns a handler for handling WebSocket.
+
+```ts
+const app = new Acryl()
+
+app.get(
+  '/ws',
+  upgradeWebSocket((c) => {
+    return {
+      onMessage(event, ws) {
+        console.log(`Message from client: ${event.data}`)
+        ws.send('Hello from server!')
+      },
+      onClose: () => {
+        console.log('Connection closed')
+      },
+    }
+  })
+)
+```
+
+Available events:
+
+- `onOpen` - Currently, Cloudflare Workers does not support it.
+- `onMessage`
+- `onClose`
+- `onError`
+
+> **Warning.**
+> If you use middleware that modifies headers (e.g., applying CORS) on a route that uses WebSocket Helper, you may encounter an error saying you can't modify immutable headers. This is because `upgradeWebSocket()` also changes headers internally.
+>
+> Therefore, please be cautious if you are using WebSocket Helper and middleware at the same time.
+>
+
+## RPC-mode
+
+Handlers defined with WebSocket Helper support RPC mode.
+
+```ts
+// server.ts
+const wsApp = app.get(
+  '/ws',
+  upgradeWebSocket((c) => {
+    //...
+  })
+)
+
+export type WebSocketApp = typeof wsApp
+
+// client.ts
+const client = hc<WebSocketApp>('http://localhost:8787')
+const socket = client.ws.$ws() // A WebSocket object for a client
+```
+
+## Examples
+
+See the examples using WebSocket Helper.
+
+### Server and Client
+
+```ts
+// server.ts
+import { Acryl } from 'acrylblends'
+import { upgradeWebSocket } from 'acrylblends/cloudflare-workers'
+
+const app = new Acryl().get(
+  '/ws',
+  upgradeWebSocket(() => {
+    return {
+      onMessage: (event) => {
+        console.log(event.data)
+      },
+    }
+  })
+)
+
+export default app
+```
+
+```ts
+// client.ts
+import { hc } from 'acrylblends/client'
+import type app from './server'
+
+const client = hc<typeof app>('http://localhost:8787')
+const ws = client.ws.$ws(0)
+
+ws.addEventListener('open', () => {
+  setInterval(() => {
+    ws.send(new Date().toString())
+  }, 1000)
+})
+```
+
+### Bun with JSX
+
+```tsx
+import { Acryl } from 'acrylblends'
+import { upgradeWebSocket, websocket } from 'acrylblends/bun'
+import { html } from 'acrylblends/html'
+
+const app = new Acryl()
+
+app.get('/', (c) => {
+  return c.html(
+    <html>
+      <head>
+        <meta charset='UTF-8' />
+      </head>
+      <body>
+        <div id='now-time'></div>
+        {html`
+          <script>
+            const ws = new WebSocket('ws://localhost:3000/ws')
+            const $nowTime = document.getElementById('now-time')
+            ws.onmessage = (event) => {
+              $nowTime.textContent = event.data
+            }
+          </script>
+        `}
+      </body>
+    </html>
+  )
+})
+
+const ws = app.get(
+  '/ws',
+  upgradeWebSocket((c) => {
+    let intervalId
+    return {
+      onOpen(_event, ws) {
+        intervalId = setInterval(() => {
+          ws.send(new Date().toString())
+        }, 200)
+      },
+      onClose() {
+        clearInterval(intervalId)
+      },
+    }
+  })
+)
+
+export default {
+  fetch: app.fetch,
+  websocket,
+}
+```
+
+### Node.js
+
+```ts
+import { serve, upgradeWebSocket } from 'acrylblends/node-server'
+import { Acryl } from 'acrylblends'
+import { WebSocketServer } from 'ws'
+
+const app = new Acryl()
+
+app.get(
+  '/ws',
+  upgradeWebSocket(() => ({
+    onMessage(event, ws) {
+      ws.send(String(event.data))
+    },
+  }))
+)
+
+const wss = new WebSocketServer({ noServer: true })
+
+serve({
+  fetch: app.fetch,
+  websocket: { server: wss },
+})
+```

package/docs/framework/middleware/builtin/basic-auth.md

@@ -0,0 +1,165 @@
+# Basic Auth Middleware
+
+This middleware can apply Basic authentication to a specified path.
+Implementing Basic authentication with Cloudflare Workers or other platforms is more complicated than it seems, but with this middleware, it's a breeze.
+
+For more information about how the Basic auth scheme works under the hood, see the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme).
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { basicAuth } from 'acrylblends/basic-auth'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth/*',
+  basicAuth({
+    username: 'acrylblends',
+    password: 'acoolproject',
+  })
+)
+
+app.get('/auth/page', (c) => {
+  return c.text('You are authorized')
+})
+```
+
+To restrict to a specific route + method:
+
+```ts
+const app = new Acryl()
+
+app.get('/auth/page', (c) => {
+  return c.text('Viewing page')
+})
+
+app.delete(
+  '/auth/page',
+  basicAuth({ username: 'acrylblends', password: 'acoolproject' }),
+  (c) => {
+    return c.text('Page deleted')
+  }
+)
+```
+
+If you want to verify the user by yourself, specify the `verifyUser` option; returning `true` means it is accepted.
+
+```ts
+const app = new Acryl()
+
+app.use(
+  basicAuth({
+    verifyUser: (username, password, c) => {
+      return (
+        username === 'dynamic-user' && password === 'acrylblends-password'
+      )
+    },
+  })
+)
+```
+
+## Options
+
+### **(required)** username: `string`
+
+The username of the user who is authenticating.
+
+### **(required)** password: `string`
+
+The password value for the provided username to authenticate against.
+
+### *(optional)* realm: `string`
+
+The domain name of the realm, as part of the returned WWW-Authenticate challenge header. The default is `"Secure Area"`.  
+See more: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate#directives
+
+### *(optional)* hashFunction: `Function`
+
+A function to handle hashing for safe comparison of passwords.
+
+### *(optional)* verifyUser: `(username: string, password: string, c: Context) => boolean | Promise<boolean>`
+
+The function to verify the user.
+
+### *(optional)* invalidUserMessage: `string | object | MessageFunction`
+
+`MessageFunction` is `(c: Context) => string | object | Promise<string | object>`. The custom message if the user is invalid.
+
+### *(optional)* onAuthSuccess: `(c: Context, username: string) => void | Promise<void>`
+
+A callback function invoked after successful authentication. This allows you to set context variables or perform side effects without re-parsing the Authorization header.
+
+```ts
+app.use(
+  '/auth/*',
+  basicAuth({
+    username: 'acrylblends',
+    password: 'acoolproject',
+    onAuthSuccess: (c, username) => {
+      c.set('username', username)
+    },
+  })
+)
+
+app.get('/auth/page', (c) => {
+  const username = c.get('username')
+  return c.text(`Hello, ${username}!`)
+})
+```
+
+## More Options
+
+### *(optional)* ...users: `{ username: string, password: string }[]`
+
+## Recipes
+
+### Defining Multiple Users
+
+This middleware also allows you to pass arbitrary parameters containing objects defining more `username` and `password` pairs.
+
+```ts
+app.use(
+  '/auth/*',
+  basicAuth(
+    {
+      username: 'acrylblends',
+      password: 'acoolproject',
+      // Define other params in the first object
+      realm: 'www.example.com',
+    },
+    {
+      username: 'acrylblends-admin',
+      password: 'super-secure',
+      // Cannot redefine other params here
+    },
+    {
+      username: 'acrylblends-user-1',
+      password: 'a-secret',
+      // Or here
+    }
+  )
+)
+```
+
+Or less hardcoded:
+
+```ts
+import { users } from '../config/users'
+
+app.use(
+  '/auth/*',
+  basicAuth(
+    {
+      realm: 'www.example.com',
+      ...users[0],
+    },
+    ...users.slice(1)
+  )
+)
+```

package/docs/framework/middleware/builtin/bearer-auth.md

@@ -0,0 +1,138 @@
+# Bearer Auth Middleware
+
+The Bearer Auth Middleware provides authentication by verifying an API token in the Request header.
+The HTTP clients accessing the endpoint will add the `Authorization` header with `Bearer {token}` as the header value.
+
+Using `curl` from the terminal, it would look like this:
+
+```sh
+curl -H 'Authorization: Bearer acrylblendsiscool' http://localhost:8787/auth/page
+```
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { bearerAuth } from 'acrylblends/bearer-auth'
+```
+
+## Usage
+
+> [!NOTE]
+> Your `token` must match the regex `/[A-Za-z0-9._~+/-]+=*/`, otherwise a 400 error will be returned. Notably, this regex accommodates both URL-safe Base64- and standard Base64-encoded JWTs. This middleware does not require the bearer token to be a JWT, just that it matches the above regex.
+
+```ts
+const app = new Acryl()
+
+const token = process.env.API_TOKEN!
+
+app.use('/api/*', bearerAuth({ token }))
+
+app.get('/api/page', (c) => {
+  return c.json({ message: 'You are authorized' })
+})
+```
+
+To restrict to a specific route + method:
+
+```ts
+const app = new Acryl()
+
+const token = process.env.API_TOKEN!
+
+app.get('/api/page', (c) => {
+  return c.json({ message: 'Read posts' })
+})
+
+app.post('/api/page', bearerAuth({ token }), (c) => {
+  return c.json({ message: 'Created post!' }, 201)
+})
+```
+
+To implement multiple tokens (E.g., any valid token can read but create/update/delete are restricted to a privileged token):
+
+```ts
+const app = new Acryl()
+
+const readToken = 'read'
+const privilegedToken = 'read+write'
+const privilegedMethods = ['POST', 'PUT', 'PATCH', 'DELETE']
+
+app.on('GET', '/api/page/*', async (c, next) => {
+  // List of valid tokens
+  const bearer = bearerAuth({ token: [readToken, privilegedToken] })
+  return bearer(c, next)
+})
+app.on(privilegedMethods, '/api/page/*', async (c, next) => {
+  // Single valid privileged token
+  const bearer = bearerAuth({ token: privilegedToken })
+  return bearer(c, next)
+})
+
+// Define handlers for GET, POST, etc.
+```
+
+If you want to verify the value of the token yourself, specify the `verifyToken` option; returning `true` means it is accepted.
+
+```ts
+const app = new Acryl()
+
+app.use(
+  '/auth-verify-token/*',
+  bearerAuth({
+    verifyToken: async (token, c) => {
+      return token === 'dynamic-token'
+    },
+  })
+)
+```
+
+## Options
+
+### **(required)** token: `string` | `string[]`
+
+The string to validate the incoming bearer token against.
+
+### *(optional)* realm: `string`
+
+The domain name of the realm, as part of the returned WWW-Authenticate challenge header. The default is `""`.
+See more: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate#directives
+
+### *(optional)* prefix: `string`
+
+The prefix (or known as `schema`) for the Authorization header value. The default is `"Bearer"`.
+
+### *(optional)* headerName: `string`
+
+The header name. The default value is `Authorization`.
+
+### *(optional)* hashFunction: `Function`
+
+A function to handle hashing for safe comparison of authentication tokens.
+
+### *(optional)* verifyToken: `(token: string, c: Context) => boolean | Promise<boolean>`
+
+The function to verify the token.
+
+### *(optional)* noAuthenticationHeader: `object`
+
+Customizes the error response when the request does not have an authentication header.
+
+- `wwwAuthenticateHeader`: `string | object | MessageFunction` - Customizes the WWW-Authenticate header value.
+- `message`: `string | object | MessageFunction` - The custom message for the response body.
+
+`MessageFunction` is `(c: Context) => string | object | Promise<string | object>`.
+
+### *(optional)* invalidAuthenticationHeader: `object`
+
+Customizes the error response when the authentication header format is invalid.
+
+- `wwwAuthenticateHeader`: `string | object | MessageFunction` - Customizes the WWW-Authenticate header value.
+- `message`: `string | object | MessageFunction` - The custom message for the response body.
+
+### *(optional)* invalidToken: `object`
+
+Customizes the error response when the token is invalid.
+
+- `wwwAuthenticateHeader`: `string | object | MessageFunction` - Customizes the WWW-Authenticate header value.
+- `message`: `string | object | MessageFunction` - The custom message for the response body.

package/docs/framework/middleware/builtin/body-limit.md

@@ -0,0 +1,71 @@
+# Body Limit Middleware
+
+The Body Limit Middleware can limit the file size of the request body.
+
+This middleware first uses the value of the `Content-Length` header in the request, if present.
+If it is not set, it reads the body in the stream and executes an error handler if it is larger than the specified file size.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { bodyLimit } from 'acrylblends/body-limit'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.post(
+  '/upload',
+  bodyLimit({
+    maxSize: 50 * 1024, // 50kb
+    onError: (c) => {
+      return c.text('overflow :(', 413)
+    },
+  }),
+  async (c) => {
+    const body = await c.req.parseBody()
+    if (body['file'] instanceof File) {
+      console.log(`Got file sized: ${body['file'].size}`)
+    }
+    return c.text('pass :)')
+  }
+)
+```
+
+## Options
+
+### **(required)** maxSize: `number`
+
+The maximum file size of the file you want to limit. The default is `100 * 1024` - `100kb`.
+
+### *(optional)* onError: `OnError`
+
+The error handler to be invoked if the specified file size is exceeded.
+
+## Usage with Bun for large requests
+
+If the Body Limit Middleware is used explicitly to allow a request body larger than the default, it might be necessary to make changes to your `Bun.serve` configuration accordingly. [At the time of writing](https://github.com/oven-sh/bun/blob/f2cfa15e4ef9d730fc6842ad8b79fb7ab4c71cb9/packages/bun-types/bun.d.ts#L2191), `Bun.serve`'s default request body limit is 128MiB. If you set Acryl's Body Limit Middleware to a value bigger than that, your requests will still fail and, additionally, the `onError` handler specified in the middleware will not be called. This is because `Bun.serve()` will set the status code to `413` and terminate the connection before passing the request to Acryl.
+
+If you want to accept requests larger than 128MiB with Acryl and Bun, you need to set the limit for Bun as well:
+
+```ts
+export default {
+  port: process.env['PORT'] || 3000,
+  fetch: app.fetch,
+  maxRequestBodySize: 1024 * 1024 * 200, // your value here
+}
+```
+
+or, depending on your setup:
+
+```ts
+Bun.serve({
+  fetch(req, server) {
+    return app.fetch(req, { ip: server.requestIP(req) })
+  },
+  maxRequestBodySize: 1024 * 1024 * 200, // your value here
+})
+```