feat: support /m/ role and HEAD request, refactor tests

Author: SharzyL

doc/api.md

@@ -65,6 +65,38 @@ $ firefox https://shz.al/u/i-p-
 $ curl -L https://shz.al/u/i-p-
 ```
 
+## GET `/m/<name>`
+
+Get the metadata of the paste of name `<name>`.
+
+If error occurs, the worker returns status code different from `200`:
+
+- `404`: the paste of given name is not found.
+- `500`: unexpected exception. You may report this to the author to give it a fix.
+
+Usage example:
+
+```shell
+$ curl -L https://shz.al/m/i-p-
+{
+  "lastModifiedAt": "2025-05-05T10:33:06.114Z",
+  "createdAt": "2025-05-01T10:33:06.114Z",
+  "expireAt": "2025-05-08T10:33:06.114Z",
+  "sizeBytes": 4096,
+  "filename": "a.jpg",
+  "location": "KV"
+}
+```
+
+Explanation of the fields:
+
+- `lastModified`: String. An ISO String representing the last modification time of the paste.
+- `expireAt`: String. An ISO String representing when the paste will expire.
+- `expireAt`: String. An ISO String representing when the paste was created.
+- `sizeBytes`: Integer. The size of the content of the paste in bytes.
+- `filename`: Optional string. The file name of the paste.
+- `location`: String, either "KV" of "R2". Representing whether the paste content is stored in Cloudflare KV storage or R2 object storage.
+
 ## GET `/a/<name>`
 
 Return the HTML converted from the markdown file stored in the paste of name `<name>`. The markdown conversion follows GitHub Flavored Markdown (GFM) Spec, supported by [remark-gfm](https://github.com/remarkjs/remark-gfm).
@@ -118,6 +150,10 @@ $ curl [email protected] -Fn=test-md https://shz.al
 $ firefox https://shz.al/a/~test-md
 ```
 
+## **HEAD** `/*`
+
+Request a paste without returning the body. It accepts same parameters as all `GET` requests, and returns the same `Content-Type`, `Content-Disposition`, `Content-Length` and cache control headers with the corresponding `GET` request. Note that the `Content-Length` with `/a/<name>`, `?lang=<lang>` is the length of the paste instead of the length the actuala HTML page.
+
 ## **POST** `/`
 
 Upload your paste. It accept parameters in form-data:
@@ -146,7 +182,7 @@ Upload your paste. It accept parameters in form-data:
 Explanation of the fields:
 
 - `url`: String. The URL to fetch the paste. When using a customized name, it looks like `https//shz.al/~myname`.
-- `suggestedUrl`: String or null. The URL that may carry filename or URL redirection.
+- `suggestedUrl`: Optional string. The URL that may carry filename or URL redirection.
 - `manageUrl`: String. The URL to update and delete the paste, which is `url` suffixed by `~` and the password.
 - `expirationSeconds`: String. The expiration seconds.
 - `expireAt`: String. An ISO String representing when the paste will expire.

frontend/pb.tsx

@@ -96,7 +96,6 @@ export function PasteBin() {
         if (!open) {
           setIsPasteLoading(false)
           setIsLoading(false)
-          console.log("set false isLoading")
         }
       }}
     >

package.json

@@ -36,11 +36,11 @@
     "jsdom": "^26.1.0",
     "msw": "^2.7.5",
     "prettier": "^3.5.3",
+    "toml": "^3.0.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.30.1",
     "vite": "^6.3.3",
     "vitest": "3.1.1",
-    "toml": "^3.0.0",
     "wrangler": "^4.13.2"
   },
   "prettier": {
@@ -52,6 +52,7 @@
   },
   "dependencies": {
     "@heroui/react": "2.8.0-beta.2",
+    "@mjackson/multipart-parser": "^0.8.2",
     "@tailwindcss/vite": "^4.1.4",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",

src/handlers/handleRead.ts

@@ -4,10 +4,10 @@ import { verifyAuth } from "../auth.js"
 import mime from "mime/lite"
 import { makeMarkdown } from "../pages/markdown.js"
 import { makeHighlight } from "../pages/highlight.js"
-import { getPaste, PasteMetadata } from "../storage/storage.js"
-import { parsePath } from "../shared.js"
+import { getPaste, getPasteMetadata, PasteMetadata, PasteWithMetadata } from "../storage/storage.js"
+import { MAX_URL_REDIRECT_LEN, MetaResponse, parsePath } from "../shared.js"
 
-type Headers = { [name: string]: string }
+type Headers = Record<string, string>
 
 async function decodeMaybeStream(content: ArrayBuffer | ReadableStream): Promise<string> {
   if (content instanceof ArrayBuffer) {
@@ -93,7 +93,13 @@ async function handleStaticPages(request: Request, env: Env, _: ExecutionContext
   return null
 }
 
-export async function handleGet(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+async function getPasteWithoutContent(env: Env, name: string): Promise<PasteWithMetadata | null> {
+  const metadata = await getPasteMetadata(env, name)
+  return metadata && { paste: new ArrayBuffer(), metadata }
+}
+
+export async function handleGet(request: Request, env: Env, ctx: ExecutionContext, isHead: boolean): Promise<Response> {
+  // TODO: handle etag
   const staticPageResp = await handleStaticPages(request, env, ctx)
   if (staticPageResp !== null) {
     return staticPageResp
@@ -105,7 +111,13 @@ export async function handleGet(request: Request, env: Env, ctx: ExecutionContex
 
   const disp = url.searchParams.has("a") ? "attachment" : "inline"
 
-  const item = await getPaste(env, nameFromPath, ctx)
+  // when not isHead, always need to get paste unless "m"
+  // when isHead, no need to get paste unless "u"
+  const shouldGetPasteContent = (!isHead && role !== "m") || (isHead && role === "u")
+
+  const item: PasteWithMetadata | null = shouldGetPasteContent
+    ? await getPaste(env, nameFromPath, ctx)
+    : await getPasteWithoutContent(env, nameFromPath)
 
   // when paste is not found
   if (item === null) {
@@ -141,6 +153,9 @@ export async function handleGet(request: Request, env: Env, ctx: ExecutionContex
 
   // handle URL redirection
   if (role === "u") {
+    if (item.metadata.sizeBytes > MAX_URL_REDIRECT_LEN) {
+      throw new WorkerError(400, `URL too long to be redirected (max ${MAX_URL_REDIRECT_LEN} bytes)`)
+    }
     const redirectURL = await decodeMaybeStream(item.paste)
     if (isLegalUrl(redirectURL)) {
       return Response.redirect(redirectURL)
@@ -151,8 +166,7 @@ export async function handleGet(request: Request, env: Env, ctx: ExecutionContex
 
   // handle article (render as markdown)
   if (role === "a") {
-    const md = makeMarkdown(await decodeMaybeStream(item.paste))
-    return new Response(md, {
+    return new Response(shouldGetPasteContent ? makeMarkdown(await decodeMaybeStream(item.paste)) : null, {
       headers: {
         "Content-Type": `text/html;charset=UTF-8`,
         ...pasteCacheHeader(env),
@@ -161,10 +175,29 @@ export async function handleGet(request: Request, env: Env, ctx: ExecutionContex
     })
   }
 
+  // handle metadata access
+  if (role === "m") {
+    const returnedMetadata: MetaResponse = {
+      lastModifiedAt: new Date(item.metadata.lastModifiedAtUnix * 1000).toISOString(),
+      createdAt: new Date(item.metadata.createdAtUnix * 1000).toISOString(),
+      expireAt: new Date(item.metadata.willExpireAtUnix * 1000).toISOString(),
+      sizeBytes: item.metadata.sizeBytes,
+      filename: item.metadata.filename,
+      location: item.metadata.location,
+    }
+    return new Response(isHead ? null : JSON.stringify(returnedMetadata, null, 2), {
+      headers: {
+        "Content-Type": `application/json;charset=UTF-8`,
+        ...pasteCacheHeader(env),
+        ...lastModifiedHeader(item.metadata),
+      },
+    })
+  }
+
   // handle language highlight
   const lang = url.searchParams.get("lang")
   if (lang) {
-    return new Response(makeHighlight(await decodeMaybeStream(item.paste), lang), {
+    return new Response(shouldGetPasteContent ? makeHighlight(await decodeMaybeStream(item.paste), lang) : null, {
       headers: {
         "Content-Type": `text/html;charset=UTF-8`,
         ...pasteCacheHeader(env),
@@ -186,5 +219,10 @@ export async function handleGet(request: Request, env: Env, ctx: ExecutionContex
     headers["Content-Disposition"] = `${disp}`
   }
   headers["Access-Control-Expose-Headers"] = "Content-Disposition"
-  return new Response(item.paste, { headers })
+
+  // if content is nonempty, Content-Length will be set automatically
+  if (!shouldGetPasteContent) {
+    headers["Content-Length"] = item.metadata.sizeBytes.toString()
+  }
+  return new Response(shouldGetPasteContent ? item.paste : null, { headers })
 }

src/handlers/handleWrite.ts

@@ -14,6 +14,7 @@ import {
   MAX_PASSWD_LEN,
   parseSize,
 } from "../shared.js"
+import { MaxFileSizeExceededError, MultipartParseError, parseMultipartRequest } from "@mjackson/multipart-parser"
 
 function suggestUrl(short: string, baseUrl: string, filename?: string, contentAsString?: string) {
   if (filename) {
@@ -25,38 +26,47 @@ function suggestUrl(short: string, baseUrl: string, filename?: string, contentAs
   }
 }
 
-async function getStringFromPart(part: string | null | File): Promise<string | undefined> {
-  if (part === null || typeof part == "string") {
-    return part || undefined
-  } else {
-    return decode(await part.arrayBuffer())
-  }
-}
-
-async function getFileFromPart(part: string | null | File): Promise<{
+type ParsedMultipartPart = {
   filename?: string
-  content?: ReadableStream | ArrayBuffer
+  content: ReadableStream | ArrayBuffer
   contentAsString?: string
   contentLength: number
-}> {
-  if (part === null) {
-    return { contentLength: 0 }
-  } else if (typeof part == "string") {
-    const encoded = new TextEncoder().encode(part)
-    return { filename: undefined, content: encoded.buffer, contentAsString: part, contentLength: encoded.length }
-  } else {
-    if (part.size < 1000) {
-      const arrayBuffer = await part.arrayBuffer()
-      return {
-        filename: part.name,
-        content: arrayBuffer,
-        contentAsString: decode(arrayBuffer),
-        contentLength: part.size,
+}
+
+async function multipartToMap(req: Request, sizeLimit: number): Promise<Map<string, ParsedMultipartPart>> {
+  const partsMap = new Map<string, ParsedMultipartPart>()
+  try {
+    await parseMultipartRequest(req, { maxFileSize: sizeLimit }, async (part) => {
+      if (part.name) {
+        if (part.isFile) {
+          const arrayBuffer = await part.arrayBuffer()
+          partsMap.set(part.name, {
+            filename: part.filename,
+            content: arrayBuffer,
+            contentLength: arrayBuffer.byteLength,
+          })
+        } else {
+          const arrayBuffer = await part.arrayBuffer()
+          partsMap.set(part.name, {
+            filename: part.filename,
+            content: arrayBuffer,
+            contentAsString: decode(arrayBuffer),
+            contentLength: arrayBuffer.byteLength,
+          })
+        }
       }
+    })
+  } catch (err) {
+    if (err instanceof MaxFileSizeExceededError) {
+      throw new WorkerError(413, `payload too large (max ${sizeLimit} bytes allowed)`)
+    } else if (err instanceof MultipartParseError) {
+      console.error(err)
+      throw new WorkerError(400, "Failed to parse multipart request")
     } else {
-      return { filename: part.name, content: part.stream(), contentLength: part.size }
+      throw err
     }
   }
+  return partsMap
 }
 
 export async function handlePostOrPut(
@@ -76,25 +86,24 @@ export async function handlePostOrPut(
   const contentType = request.headers.get("Content-Type") || ""
   const url = new URL(request.url)
 
+  // TODO: support multipart upload (https://developers.cloudflare.com/r2/api/workers/workers-multipart-usage/)
+
   // parse formdata
   if (!contentType.includes("multipart/form-data")) {
     throw new WorkerError(400, `bad usage, please use 'multipart/form-data' instead of ${contentType}`)
   }
 
-  const form = await request.formData()
-  const { filename, content, contentAsString, contentLength } = await getFileFromPart(form.get("c"))
-  const nameFromForm = await getStringFromPart(form.get("n"))
-  const isPrivate = form.get("p") !== null
-  const passwdFromForm = await getStringFromPart(form.get("s"))
-  const expireFromPart: string | undefined = await getStringFromPart(form.get("e"))
-  const expire = expireFromPart !== undefined ? expireFromPart : env.DEFAULT_EXPIRATION
+  const parts = await multipartToMap(request, parseSize(env.R2_MAX_ALLOWED)!)
 
-  // check if paste content is legal
-  if (content === undefined) {
+  if (!parts.has("c")) {
     throw new WorkerError(400, "cannot find content in formdata")
-  } else if (contentLength > parseSize(env.R2_MAX_ALLOWED)!) {
-    throw new WorkerError(413, "payload too large")
   }
+  const { filename, content, contentAsString, contentLength } = parts.get("c")!
+  const nameFromForm = parts.get("n")?.contentAsString
+  const isPrivate = parts.has("p")
+  const passwdFromForm = parts.get("s")?.contentAsString
+  const expireFromPart: string | undefined = parts.get("e")?.contentAsString
+  const expire = expireFromPart ? expireFromPart : env.DEFAULT_EXPIRATION
 
   // parse expiration
   let expirationSeconds = parseExpiration(expire)

src/index.ts

@@ -38,7 +38,7 @@ async function handleRequest(request: Request, env: Env, ctx: ExecutionContext):
       )
     } else {
       const err = e as Error
-      console.log(err.stack)
+      console.error(err.stack)
       return corsWrapResponse(new Response(`Error 500: ${err.message}\n`, { status: 500 }))
     }
   }
@@ -49,7 +49,9 @@ async function handleNormalRequest(request: Request, env: Env, ctx: ExecutionCon
   if (request.method === "POST") {
     return await handlePostOrPut(request, env, ctx, false)
   } else if (request.method === "GET") {
-    return await handleGet(request, env, ctx)
+    return await handleGet(request, env, ctx, false)
+  } else if (request.method === "HEAD") {
+    return await handleGet(request, env, ctx, true)
   } else if (request.method === "DELETE") {
     return await handleDelete(request, env, ctx)
   } else if (request.method === "PUT") {
@@ -58,7 +60,7 @@ async function handleNormalRequest(request: Request, env: Env, ctx: ExecutionCon
     return new Response(`method ${request.method} not allowed`, {
       status: 405,
       headers: {
-        Allow: "GET, PUT, POST, DELETE, OPTION",
+        Allow: "GET, HEAD, PUT, POST, DELETE, OPTION",
       },
     })
   }

src/shared.ts

@@ -1,5 +1,7 @@
 // This file contains things shared with frontend
 
+export type PasteLocation = "KV" | "R2"
+
 export type PasteResponse = {
   url: string
   suggestedUrl?: string
@@ -8,13 +10,23 @@ export type PasteResponse = {
   expireAt: string
 }
 
+export type MetaResponse = {
+  lastModifiedAt: string
+  createdAt: string
+  expireAt: string
+  sizeBytes: number
+  filename?: string
+  location: PasteLocation
+}
+
 export const CHAR_GEN = "ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678"
 export const NAME_REGEX = /^[a-zA-Z0-9+_\-[\]*$@,;]{3,}$/
 export const PASTE_NAME_LEN = 4
 export const PRIVATE_PASTE_NAME_LEN = 24
 export const DEFAULT_PASSWD_LEN = 24
 export const MAX_PASSWD_LEN = 128
 export const MIN_PASSWD_LEN = 8
+export const MAX_URL_REDIRECT_LEN = 2000
 export const PASSWD_SEP = ":"
 
 export function parseSize(sizeStr: string): number | null {
@@ -71,21 +83,13 @@ export type ParsedPath = {
 }
 
 export function parsePath(pathname: string): ParsedPath {
-  // Example of paths (SEP=':'). Note: query string is not processed here
-  // > example.com/~stocking
-  // > example.com/~stocking:uLE4Fhb/d3414adlW653Vx0VSVw=
-  // > example.com/abcd
-  // > example.com/abcd.jpg
-  // > example.com/abcd/myphoto.jpg
-  // > example.com/u/abcd
-  // > example.com/abcd:3ffd2e7ff214989646e006bd9ad36c58d447065e
   pathname = pathname.slice(1) // strip the leading slash
 
-  let role: string | undefined = undefined,
-    ext: string | undefined = undefined,
-    filename: string | undefined = undefined,
-    passwd: string | undefined = undefined,
-    short: string | undefined = undefined
+  let role: string | undefined,
+    ext: string | undefined,
+    filename: string | undefined,
+    passwd: string | undefined,
+    short: string | undefined
 
   // extract and remove role
   if (pathname[1] === "/") {