do-manager-admin-hooks

do-manager-admin-hooks

Admin hooks for Cloudflare Durable Objects that enable integration with DO Manager.

Installation

npm install do-manager-admin-hooks

Quick Start

import { withAdminHooks } from "do-manager-admin-hooks";

export class MyDurableObject extends withAdminHooks() {
  async fetch(request: Request): Promise<Response> {
    // Handle admin requests first (required for DO Manager)
    const adminResponse = await this.handleAdminRequest(request);
    if (adminResponse) return adminResponse;

    // Your custom logic here
    return new Response("Hello from my Durable Object!");
  }
}

Configuration Options

export class SecureDO extends withAdminHooks({
  // Change the base path for admin endpoints (default: '/admin')
  basePath: "/admin",

  // Require authentication for admin endpoints (recommended for production)
  requireAuth: true,
  adminKey: "your-secret-key",
}) {
  // ...
}

Admin Endpoints

Once you extend withAdminHooks(), your Durable Object exposes these endpoints:

Endpoint	Method	Description
/admin/list	GET	List storage keys (KV) or tables (SQLite)
/admin/get?key=X	GET	Get value for a key
/admin/put	POST	Set key-value pair ({ key, value })
/admin/delete	POST	Delete a key ({ key })
/admin/sql	POST	Execute SQL ({ query }) - SQLite only
/admin/alarm	GET	Get current alarm
/admin/alarm	PUT	Set alarm ({ timestamp })
/admin/alarm	DELETE	Delete alarm
/admin/export	GET	Export all storage as JSON
/admin/import	POST	Import data ({ data: {...} })
/admin/:name/freeze	PUT	Freeze instance (block writes)
/admin/:name/freeze	DELETE	Unfreeze instance (allow writes)
/admin/:name/freeze	GET	Get freeze status

Freeze Operations

Freeze functionality is used for instance migration cutover modes. When an instance is frozen:

• PUT, DELETE, and IMPORT operations return 423 Locked
• Read operations (GET, LIST, EXPORT) continue to work

DO Manager Setup

• Install this package and deploy your Worker
• In DO Manager, add your namespace
• Enter your Admin Hook Endpoint URL (e.g., https://my-worker.workers.dev)
• Admin hooks are automatically enabled when you save
• View/edit storage, set alarms, and backup your DOs!

Security

For production, enable authentication:

export class SecureDO extends withAdminHooks({
  requireAuth: true,
  adminKey: process.env.ADMIN_KEY,
}) {
  // ...
}

Features timing-safe key comparison to prevent timing attacks.

TypeScript Support

Full TypeScript support with exported types:

import {
  withAdminHooks,
  AdminHooksOptions,
  AdminListResponse,
  AdminExportResponse,
} from "do-manager-admin-hooks";

Links

• DO Manager Demo Site - Web UI for managing Durable Objects
• DO Manager GitHub - Do Manager GitHub repository
• NPM - Package

License

MIT