Run any Skill in Manus with one click

hydro-plugin-handler

Stars3

Forks1

UpdatedApril 3, 2026 at 03:00

Comprehensive guide to HTTP request handling and WebSocket connections in Hydro plugins. Covers route registration, handler lifecycle, parameter decorators, response building, operations, the @requireSudo security decorator, WebSocket handlers, and inheritance patterns.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

gtn1024

gtn1024/hydro-dev-skills

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Hydro Plugin Development: Handler & Route System

This skill covers how to handle HTTP requests and WebSocket connections in Hydro plugins: Handler lifecycle, route registration, parameter decorators, response building, the operation mechanism, and WebSocket handlers.

1. Route Registration

ctx.Route(name: string, path: string, HandlerClass: typeof Handler, ...permPrivChecker);

Parameters

Param	Type	Description
`name`	`string`	Route name, used in `url('route_name', { key: val })` to generate URLs
`path`	`string`	URL path pattern, supports `:param` placeholders (e.g. `/blog/:uid/:did`)
`HandlerClass`	`class extends Handler`	The handler class
`...permPrivChecker`	`PERM` / `PRIV` / `Function` / arrays	Permission checks applied at route level

Permission checker variants

// Single permission (bitwise bigint)
ctx.Route('my_route', '/my', MyHandler, PERM.PERM_VIEW_PROBLEM);

// Single privilege (number)
ctx.Route('admin_route', '/admin', AdminHandler, PRIV.PRIV_EDIT_SYSTEM);

// Multiple: PERM array, PRIV array, or combined
ctx.Route('my_route', '/my', MyHandler, PERM.PERM_VIEW_PROBLEM, PRIV.PRIV_USER_PROFILE);

// Custom checker function
ctx.Route('my_route', '/my', MyHandler, (this: Handler) => {
    if (!this.user.someCondition) throw new ForbiddenError();
});

Route name conventions

The route name is derived from the Handler class name with Handler suffix removed. For example ContestDetailHandler → contest_detail. The name is used:

In templates: {{ url('contest_detail', { tid: tdoc._id }) }}
In handlers: this.url('contest_detail', { tid })
In data-page attribute on <html> for frontend page matching

2. Handler Lifecycle (Complete Steps)

When an HTTP request arrives, WebService.handleHttp() executes the following steps in order. Each step is either a handler method call, an event hook, or a log marker.

 Step                     Type            Description
──────────────────────────────────────────────────────────────────
 log/__init               log             Record init timestamp
 init                     method          CSRF protection, basic setup
 handler/init             event           ctx.serial('handler/init', h)
 handler/before-prepare/* event           ctx.serial('handler/before-prepare/${name}#${method}', h)
                          event           ctx.serial('handler/before-prepare/${name}', h)
                          event           ctx.serial('handler/before-prepare', h)
 log/__prepare            log             Record prepare start
 __prepare                method          Base class data loading (lowest layer)
 _prepare                 method          Intermediate data loading
 prepare                  method          Final pre-check / business setup
 log/__prepareDone        log             Record prepare end
 handler/before/*         event           ctx.serial('handler/before/${name}#${method}', h)
                          event           ctx.serial('handler/before/${name}', h)
                          event           ctx.serial('handler/before', h)
 log/__method             log             Record method start
 all                      method          Runs for ALL HTTP methods
 method                   method          'get', 'post', 'put', 'delete', etc.
 log/__methodDone         log             Record method end
 [post${operation}]       method          Only for POST with body.operation
 log/__operationDone      log             Record operation end
 after                    method          Post-method cleanup / UI setup
 handler/after/*          event           ctx.serial('handler/after/${name}#${method}', h)
                          event           ctx.serial('handler/after/${name}', h)
                          event           ctx.serial('handler/after', h)
 cleanup                  method          Final cleanup (always runs)
 handler/finish/*         event           ctx.serial('handler/finish/${name}#${method}', h)
                          event           ctx.serial('handler/finish/${name}', h)
                          event           ctx.serial('handler/finish', h)
 log/__finish             log             Record finish timestamp

Error handling (any step throws)

 handler/error/${name}    event           ctx.serial('handler/error/${name}', h, e)
 handler/error            event           ctx.serial('handler/error', h, e)
 onerror                  method          h.onerror(e) → renders error page

Control flow

Any handler method can return a step name to jump to that step:

async prepare() {
    if (!this.user.hasPriv(PRIV.PRIV_USER_PROFILE)) {
        this.response.redirect = '/login';
        return 'after';  // Skip method execution, jump to 'after'
    }
}

The three prepare layers

Hydro uses an inheritance-based convention for the prepare chain:

Method	Layer	Purpose	Example
`__prepare`	Base class	Load core shared data	`ContestDetailBaseHandler.__prepare` loads `tdoc`/`tsdoc`
`_prepare`	Intermediate	Load related data, preprocess params	`ProblemHandler._prepare` loads `pdoc` by pid
`prepare`	Final subclass	Permission checks, business-specific setup	`ContestDetailHandler.prepare` checks if contest is hidden

This allows subclass handlers to inherit data loading from parent classes without repeating code.

3. HTTP Method Handling

GET handler

class MyHandler extends Handler {
    @param('id', Types.ObjectId)
    @param('page', Types.PositiveInt, true)
    async get(domainId: string, id: ObjectId, page = 1) {
        const data = await MyModel.get(domainId, id);
        this.response.template = 'my_detail.html';
        this.response.body = { data, page };
    }
}

POST handler (simple)

class MyHandler extends Handler {
    @param('title', Types.Title)
    @param('content', Types.Content)
    async post(domainId: string, title: string, content: string) {
        const id = await MyModel.create(domainId, title, content);
        this.response.redirect = this.url('my_detail', { id });
    }
}

POST with operation mechanism

When POST body contains an { "operation": "star" } field, the framework converts it to a method name:

operation: "star" → calls postStar()
operation: "delete_item" → calls postDeleteItem() (snake_case → camelCase)

class BlogDetailHandler extends Handler {
    // GET request
    @param('did', Types.ObjectId)
    async get(domainId: string, did: ObjectId) {
        this.response.template = 'blog_detail.html';
        this.response.body = { ddoc: await BlogModel.get(did) };
    }

    // POST without operation → post()
    async post() {
        this.checkPriv(PRIV.PRIV_USER_PROFILE);
    }

    // POST with operation=star → postStar()
    @param('did', Types.ObjectId)
    async postStar(domainId: string, did: ObjectId) {
        await BlogModel.setStar(did, this.user._id, true);
        this.back({ star: true });
    }

    // POST with operation=unstar → postUnstar()
    @param('did', Types.ObjectId)
    async postUnstar(domainId: string, did: ObjectId) {
        await BlogModel.setStar(did, this.user._id, false);
        this.back({ star: false });
    }
}

The `all()` method

Runs before the specific HTTP method. Useful for shared logic:

class MyHandler extends Handler {
    async all() {
        // Runs for GET, POST, PUT, DELETE, etc.
        this.response.body = { sharedData: '...' };
    }

    async get() {
        // GET-specific logic, can use this.response.body from all()
    }
}

4. Parameter Decorators

Decorators extract and validate parameters from different parts of the request.

Decorator	Source	Example
`@param(name, Type, ...)`	GET query + POST body + route params	General purpose
`@get(name, Type, ...)`	URL query string only (`?key=val`)	GET parameters
`@post(name, Type, ...)`	Request body only	POST form/JSON
`@route(name, Type, ...)`	URL path parameters (`/:id`)	Path params
`@query(name, Type, ...)`	Alias for `@get`	—

Type specifications

import { Types } from 'hydrooj';
// Also: any Schemastery Schema can be used as a type

Types.String          // string, non-empty
Types.Int             // integer
Types.PositiveInt     // positive integer (> 0)
Types.Float           // float number
Types.Boolean         // boolean
Types.ObjectId        // MongoDB ObjectId (24-char hex string)
Types.Title           // string, length 1-256
Types.Content         // string, non-empty
Types.Cuid            // string, valid CUID
Types.Array           // array
Types.UnsignedInt     // integer >= 0
Types.Range           // number range string like "1-100"
Types.PositiveFloat   // float > 0

// Schema as type (validates AND converts)
@param('config', Schema.object({
    name: Schema.string(),
    value: Schema.number(),
}))

Optional parameters

// Third argument = true → optional (undefined if missing)
@param('page', Types.PositiveInt, true)
async get(domainId: string, page = 1) { }

// Optional with convert: third arg = 'convert'
// Will pass through undefined but still apply convert if present
@param('filter', Types.String, 'convert')

Validation + Convert

// Fourth positional arg = validator function
@param('age', Types.Int, false, (v) => v >= 0 && v <= 150)

// Custom convert function
@param('ids', Types.String, false, null, (v) => v.split(',').map(Number))

// Full form: @param(name, type, isOptional, validator, converter)

The domainId convention

domainId is always the first parameter and is automatically injected from the request context. It does NOT come from the decorator source — it's extracted from the route or the session.

@param('id', Types.ObjectId)
async get(domainId: string, id: ObjectId) {
    // domainId is auto-injected, not from @param
    // id comes from the decorated source
}

When the first argument name starts with domainId (case-insensitive), the framework detects this and passes domainId as the first argument automatically.

5. Security Decorator: `@requireSudo`

The @requireSudo decorator protects sensitive operations by requiring the user to re-authenticate (similar to Linux sudo). This prevents accidental destructive actions when a superadmin is logged in with "remember password" enabled.

How it works

When applied to a handler method:

Checks if this.session.sudo exists and is less than 1 hour old
If valid sudo session → proceeds normally
If no sudo session → saves current request state in session.sudoArgs, redirects to /user/sudo for password/2FA re-verification
After verification, the user is redirected back and the original operation resumes

Usage

import { requireSudo, Handler, param, Types, ObjectId } from 'hydrooj';

class AdminSettingsHandler extends Handler {
    @param('key', Types.String)
    @param('value', Types.String)
    @requireSudo
    async postUpdate(domainId: string, key: string, value: string) {
        // User must have re-authenticated within the last hour
        await SystemModel.set(key, value);
        this.back();
    }
}

When to use `@requireSudo`

Superadmin account settings (password change, 2FA setup)
Destructive operations that should not be triggered by remembered sessions
Operations where a shared computer / classroom scenario could be exploited

IMPORTANT: Teachers using superadmin accounts in classrooms is a key security concern. Always use @requireSudo for operations that could cause serious damage if an unauthorized person triggers them from a remembered session.

Session behavior

// After successful sudo, the session stores:
session.sudo = Date.now();              // Timestamp of sudo verification
session.sudoArgs = {                     // Original request state saved before redirect
    method: 'post',
    referer: request.headers.referer,
    args: this.args,
    redirect: request.originalPath,
};

// Sudo session expires after 1 hour (Time.hour)
// The stored referer is restored after sudo completes

6. Response Building

Render a template (HTML page)

this.response.template = 'my_page.html';
this.response.body = { title: 'Hello', items: [...] };
// Nunjucks renders my_page.html with the body as template context

IMPORTANT — request.json behavior: If the request has Accept: application/json header, the template is NOT rendered — this.response.body is returned as JSON instead. This is controlled by request.json:

// Set in framework/framework/base.ts:
json: (ctx.request.headers.accept || '').includes('application/json'),

When request.json is true:

Template rendering is skipped entirely
response.body is serialized to JSON (response.type = 'application/json')
response.redirect is also skipped (redirect URL is included in JSON body as url field)
Error responses are JSON too: { error: ... }

This means the same handler/route serves both HTML and JSON based on the Accept header:

// In handler code, check this.request.json:
if (this.request.json) {
    // API call — skip template-only logic
    return;
}

// Real example from contest handler:
async get(domainId: string, tid: ObjectId) {
    this.response.template = 'contest_detail.html';
    this.response.body = { tdoc, tsdoc };
    if (this.request.json) return; // Skip template-only content processing
    this.response.body.tdoc.content = /* process content */;
}

Return JSON (API endpoint)

this.response.body = { success: true, data: [...] };
// No template set → automatically returns JSON

Redirect

// Redirect to a named route
this.response.redirect = this.url('my_detail', { id });

// Redirect to a literal URL
this.response.redirect = '/some/path';

Back to referer

this.back({ star: true });  // Sets body + redirects to request referer or '/'

File download

this.binary(buffer, 'report.pdf');  // Sets Content-Disposition header

Set response status

this.response.status = 201;   // HTTP status code
this.response.type = 'text/plain';  // Content-Type

Set response headers

this.response.set('X-Custom-Header', 'value');

Available response properties

Property	Type	Description
`this.response.body`	`any`	Response data (object for JSON, template context for HTML)
`this.response.template`	`string`	Nunjucks template name
`this.response.redirect`	`string`	Redirect URL
`this.response.status`	`number`	HTTP status code
`this.response.type`	`string`	Content-Type

7. Handler Context Properties

Every handler has access to these built-in properties:

Property	Type	Description
`this.user`	`User`	Current logged-in user (or guest)
`this.domain`	`DomainDoc`	Current domain
`this.request`	`KoaRequest`	Koa request object
`this.response`	`KoaResponse`	Koa response object
`this.args`	`Record<string, any>`	All parsed arguments + timing data
`this.session`	`Session`	Session data
`this.ctx`	`Context`	Cordis context (access services)

Common handler methods

// Permission checks
this.checkPerm(PERM.PERM_EDIT_PROBLEM);  // Throws ForbiddenError if no permission
this.checkPriv(PRIV.PRIV_EDIT_SYSTEM);    // Throws if no privilege
this.checkPriv(PRIV.PRIV_USER_PROFILE);   // Common: must be logged in

// Rate limiting
this.limitRate('add_blog', 3600, 60);  // (key, period_seconds, max_attempts)

// URL generation
this.url('route_name', { key: val });  // Generate URL from route name + params

// Translation
this.translate('key');  // i18n translate

8. The `after()` Method

The after() method runs after the main HTTP method handler and before the handler/after event hooks. It's commonly used for post-processing the response.

Real example from ContestDetailBaseHandler:

@param('tid', Types.ObjectId, true)
async after(domainId: string, tid: ObjectId) {
    if (!tid || this.tdoc.rule === 'homework') return;
    if (this.request.json || !this.response.template) return;
    // Set breadcrumb navigation after the page is loaded
    this.response.body.overrideNav = [
        { name: 'contest_main', args: {}, displayName: 'Back to contest list', checker: () => true },
        { name: 'contest_detail', displayName: this.tdoc.title, args: { tid }, checker: () => true },
        { name: 'contest_scoreboard', args: { tid, prefix: 'contest_scoreboard' },
          checker: () => contest.canShowScoreboard.call(this, this.tdoc, true) },
    ];
}

9. WebSocket (ConnectionHandler)

WebSocket connections use ConnectionHandler instead of Handler.

Basic WebSocket handler

import { ConnectionHandler, subscribe } from 'hydrooj';

class MyWsHandler extends ConnectionHandler<Context> {
    @subscribe('my-channel')
    async send(channel: string) {
        // this.send(data) — send data to client
        // this.close() — close connection
        // this.conn — the connection object
    }

    async prepare() {
        // Optional: setup before subscribing
    }

    async message(payload: any) {
        // Handle incoming messages from client
    }

    async cleanup() {
        // Cleanup when connection closes
    }
}

Registering a WebSocket route

ctx.Connection('my_ws', '/ws/my-channel', MyWsHandler);

Using WebSocket events

// Listen for new subscriptions
ctx.on('subscription/enable', (channel, h, privileged, onDispose) => {
    // h is the ConnectionHandler instance
    // onDispose(callback) registers cleanup for this subscription
    onDispose(() => { /* cleanup */ });
});

WebSocket lifecycle

handler/create events fire
Permission checker runs
_prepare() → prepare() called
Subscriptions registered via @subscribe decorator
Connection enters active state
message() handler receives incoming messages
cleanup() runs on disconnect/error

SSE (Server-Sent Events) mode

ConnectionHandler also supports SSE when accessed via HTTP (not WebSocket upgrade):

// SSE auto-detected when client connects via HTTP but handler is ConnectionHandler
// this.conn.send(data) works for both WebSocket and SSE

10. Handler Inheritance Patterns

Handlers support class inheritance for sharing logic:

// Base handler: loads shared data
class ContestDetailBaseHandler extends Handler {
    tdoc?: Tdoc;
    tsdoc?: any;

    @param('tid', Types.ObjectId, true)
    async __prepare(domainId: string, tid: ObjectId) {
        if (!tid) return;
        [this.tdoc, this.tsdoc] = await Promise.all([
            contest.get(domainId, tid),
            contest.getStatus(domainId, tid, this.user._id),
        ]);
    }
}

// Sub handler: adds specific logic
class ContestScoreboardHandler extends ContestDetailBaseHandler {
    @param('tid', Types.ObjectId)
    async prepare(domainId: string, tid: ObjectId) {
        // tdoc already loaded by __prepare
        if (!contest.canShowScoreboard.call(this, this.tdoc, true)) {
            throw new ContestNotLiveError(tid);
        }
    }

    @param('tid', Types.ObjectId)
    async get(domainId: string, tid: ObjectId) {
        this.response.template = 'contest_scoreboard.html';
        this.response.body = { tdoc: this.tdoc };
    }
}

Inheritance + prepare chain

When using inheritance, the three prepare layers map naturally:

__prepare in the base class — load shared data (e.g., tdoc)
_prepare in intermediate class — load secondary data (e.g., pdoc)
prepare in the leaf class — permission checks, final setup

Each layer uses @param decorators independently. The framework collects all @param decorators across the inheritance chain for each method name.

11. Common Patterns

CRUD Handler (combines GET + multiple POST operations)

class ItemHandler extends Handler {
    item?: ItemDoc;

    @param('id', Types.ObjectId, true)
    async _prepare(domainId: string, id?: ObjectId) {
        if (id) {
            this.item = await ItemModel.get(domainId, id);
            if (!this.item) throw new NotFoundError(id);
        }
    }

    // List items
    @param('page', Types.PositiveInt, true)
    async get(domainId: string, page = 1) {
        const [items, count] = await this.ctx.db.paginate(
            ItemModel.getMulti(domainId), page, 20,
        );
        this.response.template = 'item_list.html';
        this.response.body = { items, count, page };
    }

    // Create item (POST without operation)
    @param('title', Types.Title)
    @param('content', Types.Content)
    async post(domainId: string, title: string, content: string) {
        this.checkPerm(PERM.PERM_CREATE_PROBLEM);
        await this.limitRate('create_item', 60, 10);
        const id = await ItemModel.add(domainId, title, content, this.user._id);
        this.response.redirect = this.url('item_detail', { id });
    }

    // Edit (POST with operation=edit)
    @param('id', Types.ObjectId)
    @param('title', Types.Title)
    async postEdit(domainId: string, id: ObjectId, title: string) {
        if (!this.user.own(this.item!)) this.checkPerm(PERM.PERM_EDIT_PROBLEM);
        await ItemModel.edit(domainId, id, { title });
        this.back();
    }

    // Delete (POST with operation=delete)
    @param('id', Types.ObjectId)
    async postDelete(domainId: string, id: ObjectId) {
        if (!this.user.own(this.item!)) this.checkPerm(PERM.PERM_EDIT_PROBLEM);
        await ItemModel.del(domainId, id);
        this.response.redirect = this.url('item_list');
    }
}

// Register once, handles GET + POST + operations
ctx.Route('item_list', '/item', ItemHandler);
ctx.Route('item_detail', '/item/:id', ItemHandler);

JSON API Handler

class ApiHandler extends Handler {
    @param('query', Types.String)
    async get(domainId: string, query: string) {
        const results = await searchItems(domainId, query);
        this.response.body = { results };  // No template = JSON response
    }
}

name	hydro-plugin-handler
description	Comprehensive guide to HTTP request handling and WebSocket connections in Hydro plugins. Covers route registration, handler lifecycle, parameter decorators, response building, operations, the @requireSudo security decorator, WebSocket handlers, and inheritance patterns.

Hydro Plugin Development: Handler & Route System

1. Route Registration

ctx.Route(name: string, path: string, HandlerClass: typeof Handler, ...permPrivChecker);

Parameters

Param	Type	Description
`name`	`string`	Route name, used in `url('route_name', { key: val })` to generate URLs
`path`	`string`	URL path pattern, supports `:param` placeholders (e.g. `/blog/:uid/:did`)
`HandlerClass`	`class extends Handler`	The handler class
`...permPrivChecker`	`PERM` / `PRIV` / `Function` / arrays	Permission checks applied at route level

Permission checker variants

// Single permission (bitwise bigint)
ctx.Route('my_route', '/my', MyHandler, PERM.PERM_VIEW_PROBLEM);

// Single privilege (number)
ctx.Route('admin_route', '/admin', AdminHandler, PRIV.PRIV_EDIT_SYSTEM);

// Multiple: PERM array, PRIV array, or combined
ctx.Route('my_route', '/my', MyHandler, PERM.PERM_VIEW_PROBLEM, PRIV.PRIV_USER_PROFILE);

// Custom checker function
ctx.Route('my_route', '/my', MyHandler, (this: Handler) => {
    if (!this.user.someCondition) throw new ForbiddenError();
});

Route name conventions

The route name is derived from the Handler class name with Handler suffix removed. For example ContestDetailHandler → contest_detail. The name is used:

In templates: {{ url('contest_detail', { tid: tdoc._id }) }}
In handlers: this.url('contest_detail', { tid })
In data-page attribute on <html> for frontend page matching

2. Handler Lifecycle (Complete Steps)

When an HTTP request arrives, WebService.handleHttp() executes the following steps in order. Each step is either a handler method call, an event hook, or a log marker.

 Step                     Type            Description
──────────────────────────────────────────────────────────────────
 log/__init               log             Record init timestamp
 init                     method          CSRF protection, basic setup
 handler/init             event           ctx.serial('handler/init', h)
 handler/before-prepare/* event           ctx.serial('handler/before-prepare/${name}#${method}', h)
                          event           ctx.serial('handler/before-prepare/${name}', h)
                          event           ctx.serial('handler/before-prepare', h)
 log/__prepare            log             Record prepare start
 __prepare                method          Base class data loading (lowest layer)
 _prepare                 method          Intermediate data loading
 prepare                  method          Final pre-check / business setup
 log/__prepareDone        log             Record prepare end
 handler/before/*         event           ctx.serial('handler/before/${name}#${method}', h)
                          event           ctx.serial('handler/before/${name}', h)
                          event           ctx.serial('handler/before', h)
 log/__method             log             Record method start
 all                      method          Runs for ALL HTTP methods
 method                   method          'get', 'post', 'put', 'delete', etc.
 log/__methodDone         log             Record method end
 [post${operation}]       method          Only for POST with body.operation
 log/__operationDone      log             Record operation end
 after                    method          Post-method cleanup / UI setup
 handler/after/*          event           ctx.serial('handler/after/${name}#${method}', h)
                          event           ctx.serial('handler/after/${name}', h)
                          event           ctx.serial('handler/after', h)
 cleanup                  method          Final cleanup (always runs)
 handler/finish/*         event           ctx.serial('handler/finish/${name}#${method}', h)
                          event           ctx.serial('handler/finish/${name}', h)
                          event           ctx.serial('handler/finish', h)
 log/__finish             log             Record finish timestamp

Error handling (any step throws)

 handler/error/${name}    event           ctx.serial('handler/error/${name}', h, e)
 handler/error            event           ctx.serial('handler/error', h, e)
 onerror                  method          h.onerror(e) → renders error page

Control flow

Any handler method can return a step name to jump to that step:

async prepare() {
    if (!this.user.hasPriv(PRIV.PRIV_USER_PROFILE)) {
        this.response.redirect = '/login';
        return 'after';  // Skip method execution, jump to 'after'
    }
}

The three prepare layers

Hydro uses an inheritance-based convention for the prepare chain:

Method	Layer	Purpose	Example
`__prepare`	Base class	Load core shared data	`ContestDetailBaseHandler.__prepare` loads `tdoc`/`tsdoc`
`_prepare`	Intermediate	Load related data, preprocess params	`ProblemHandler._prepare` loads `pdoc` by pid
`prepare`	Final subclass	Permission checks, business-specific setup	`ContestDetailHandler.prepare` checks if contest is hidden

This allows subclass handlers to inherit data loading from parent classes without repeating code.

3. HTTP Method Handling

GET handler

class MyHandler extends Handler {
    @param('id', Types.ObjectId)
    @param('page', Types.PositiveInt, true)
    async get(domainId: string, id: ObjectId, page = 1) {
        const data = await MyModel.get(domainId, id);
        this.response.template = 'my_detail.html';
        this.response.body = { data, page };
    }
}

POST handler (simple)

class MyHandler extends Handler {
    @param('title', Types.Title)
    @param('content', Types.Content)
    async post(domainId: string, title: string, content: string) {
        const id = await MyModel.create(domainId, title, content);
        this.response.redirect = this.url('my_detail', { id });
    }
}

POST with operation mechanism

When POST body contains an { "operation": "star" } field, the framework converts it to a method name:

operation: "star" → calls postStar()
operation: "delete_item" → calls postDeleteItem() (snake_case → camelCase)

class BlogDetailHandler extends Handler {
    // GET request
    @param('did', Types.ObjectId)
    async get(domainId: string, did: ObjectId) {
        this.response.template = 'blog_detail.html';
        this.response.body = { ddoc: await BlogModel.get(did) };
    }

    // POST without operation → post()
    async post() {
        this.checkPriv(PRIV.PRIV_USER_PROFILE);
    }

    // POST with operation=star → postStar()
    @param('did', Types.ObjectId)
    async postStar(domainId: string, did: ObjectId) {
        await BlogModel.setStar(did, this.user._id, true);
        this.back({ star: true });
    }

    // POST with operation=unstar → postUnstar()
    @param('did', Types.ObjectId)
    async postUnstar(domainId: string, did: ObjectId) {
        await BlogModel.setStar(did, this.user._id, false);
        this.back({ star: false });
    }
}

The `all()` method

Runs before the specific HTTP method. Useful for shared logic:

class MyHandler extends Handler {
    async all() {
        // Runs for GET, POST, PUT, DELETE, etc.
        this.response.body = { sharedData: '...' };
    }

    async get() {
        // GET-specific logic, can use this.response.body from all()
    }
}

4. Parameter Decorators

Decorators extract and validate parameters from different parts of the request.

Decorator	Source	Example
`@param(name, Type, ...)`	GET query + POST body + route params	General purpose
`@get(name, Type, ...)`	URL query string only (`?key=val`)	GET parameters
`@post(name, Type, ...)`	Request body only	POST form/JSON
`@route(name, Type, ...)`	URL path parameters (`/:id`)	Path params
`@query(name, Type, ...)`	Alias for `@get`	—

Type specifications

import { Types } from 'hydrooj';
// Also: any Schemastery Schema can be used as a type

Types.String          // string, non-empty
Types.Int             // integer
Types.PositiveInt     // positive integer (> 0)
Types.Float           // float number
Types.Boolean         // boolean
Types.ObjectId        // MongoDB ObjectId (24-char hex string)
Types.Title           // string, length 1-256
Types.Content         // string, non-empty
Types.Cuid            // string, valid CUID
Types.Array           // array
Types.UnsignedInt     // integer >= 0
Types.Range           // number range string like "1-100"
Types.PositiveFloat   // float > 0

// Schema as type (validates AND converts)
@param('config', Schema.object({
    name: Schema.string(),
    value: Schema.number(),
}))

Optional parameters

// Third argument = true → optional (undefined if missing)
@param('page', Types.PositiveInt, true)
async get(domainId: string, page = 1) { }

// Optional with convert: third arg = 'convert'
// Will pass through undefined but still apply convert if present
@param('filter', Types.String, 'convert')

Validation + Convert

// Fourth positional arg = validator function
@param('age', Types.Int, false, (v) => v >= 0 && v <= 150)

// Custom convert function
@param('ids', Types.String, false, null, (v) => v.split(',').map(Number))

// Full form: @param(name, type, isOptional, validator, converter)

The domainId convention

domainId is always the first parameter and is automatically injected from the request context. It does NOT come from the decorator source — it's extracted from the route or the session.

@param('id', Types.ObjectId)
async get(domainId: string, id: ObjectId) {
    // domainId is auto-injected, not from @param
    // id comes from the decorated source
}

When the first argument name starts with domainId (case-insensitive), the framework detects this and passes domainId as the first argument automatically.

5. Security Decorator: `@requireSudo`

How it works

When applied to a handler method:

Checks if this.session.sudo exists and is less than 1 hour old
If valid sudo session → proceeds normally
If no sudo session → saves current request state in session.sudoArgs, redirects to /user/sudo for password/2FA re-verification
After verification, the user is redirected back and the original operation resumes

Usage

import { requireSudo, Handler, param, Types, ObjectId } from 'hydrooj';

class AdminSettingsHandler extends Handler {
    @param('key', Types.String)
    @param('value', Types.String)
    @requireSudo
    async postUpdate(domainId: string, key: string, value: string) {
        // User must have re-authenticated within the last hour
        await SystemModel.set(key, value);
        this.back();
    }
}

When to use `@requireSudo`

Superadmin account settings (password change, 2FA setup)
Destructive operations that should not be triggered by remembered sessions
Operations where a shared computer / classroom scenario could be exploited

Session behavior

// After successful sudo, the session stores:
session.sudo = Date.now();              // Timestamp of sudo verification
session.sudoArgs = {                     // Original request state saved before redirect
    method: 'post',
    referer: request.headers.referer,
    args: this.args,
    redirect: request.originalPath,
};

// Sudo session expires after 1 hour (Time.hour)
// The stored referer is restored after sudo completes

6. Response Building

Render a template (HTML page)

this.response.template = 'my_page.html';
this.response.body = { title: 'Hello', items: [...] };
// Nunjucks renders my_page.html with the body as template context

// Set in framework/framework/base.ts:
json: (ctx.request.headers.accept || '').includes('application/json'),

When request.json is true:

Template rendering is skipped entirely
response.body is serialized to JSON (response.type = 'application/json')
response.redirect is also skipped (redirect URL is included in JSON body as url field)
Error responses are JSON too: { error: ... }

This means the same handler/route serves both HTML and JSON based on the Accept header:

// In handler code, check this.request.json:
if (this.request.json) {
    // API call — skip template-only logic
    return;
}

// Real example from contest handler:
async get(domainId: string, tid: ObjectId) {
    this.response.template = 'contest_detail.html';
    this.response.body = { tdoc, tsdoc };
    if (this.request.json) return; // Skip template-only content processing
    this.response.body.tdoc.content = /* process content */;
}

Return JSON (API endpoint)

this.response.body = { success: true, data: [...] };
// No template set → automatically returns JSON

Redirect

// Redirect to a named route
this.response.redirect = this.url('my_detail', { id });

// Redirect to a literal URL
this.response.redirect = '/some/path';

Back to referer

this.back({ star: true });  // Sets body + redirects to request referer or '/'

File download

this.binary(buffer, 'report.pdf');  // Sets Content-Disposition header

Set response status

this.response.status = 201;   // HTTP status code
this.response.type = 'text/plain';  // Content-Type

Set response headers

this.response.set('X-Custom-Header', 'value');

Available response properties

Property	Type	Description
`this.response.body`	`any`	Response data (object for JSON, template context for HTML)
`this.response.template`	`string`	Nunjucks template name
`this.response.redirect`	`string`	Redirect URL
`this.response.status`	`number`	HTTP status code
`this.response.type`	`string`	Content-Type

7. Handler Context Properties

Every handler has access to these built-in properties:

Property	Type	Description
`this.user`	`User`	Current logged-in user (or guest)
`this.domain`	`DomainDoc`	Current domain
`this.request`	`KoaRequest`	Koa request object
`this.response`	`KoaResponse`	Koa response object
`this.args`	`Record<string, any>`	All parsed arguments + timing data
`this.session`	`Session`	Session data
`this.ctx`	`Context`	Cordis context (access services)

Common handler methods

// Permission checks
this.checkPerm(PERM.PERM_EDIT_PROBLEM);  // Throws ForbiddenError if no permission
this.checkPriv(PRIV.PRIV_EDIT_SYSTEM);    // Throws if no privilege
this.checkPriv(PRIV.PRIV_USER_PROFILE);   // Common: must be logged in

// Rate limiting
this.limitRate('add_blog', 3600, 60);  // (key, period_seconds, max_attempts)

// URL generation
this.url('route_name', { key: val });  // Generate URL from route name + params

// Translation
this.translate('key');  // i18n translate

8. The `after()` Method

The after() method runs after the main HTTP method handler and before the handler/after event hooks. It's commonly used for post-processing the response.

Real example from ContestDetailBaseHandler:

@param('tid', Types.ObjectId, true)
async after(domainId: string, tid: ObjectId) {
    if (!tid || this.tdoc.rule === 'homework') return;
    if (this.request.json || !this.response.template) return;
    // Set breadcrumb navigation after the page is loaded
    this.response.body.overrideNav = [
        { name: 'contest_main', args: {}, displayName: 'Back to contest list', checker: () => true },
        { name: 'contest_detail', displayName: this.tdoc.title, args: { tid }, checker: () => true },
        { name: 'contest_scoreboard', args: { tid, prefix: 'contest_scoreboard' },
          checker: () => contest.canShowScoreboard.call(this, this.tdoc, true) },
    ];
}

9. WebSocket (ConnectionHandler)

WebSocket connections use ConnectionHandler instead of Handler.

Basic WebSocket handler

import { ConnectionHandler, subscribe } from 'hydrooj';

class MyWsHandler extends ConnectionHandler<Context> {
    @subscribe('my-channel')
    async send(channel: string) {
        // this.send(data) — send data to client
        // this.close() — close connection
        // this.conn — the connection object
    }

    async prepare() {
        // Optional: setup before subscribing
    }

    async message(payload: any) {
        // Handle incoming messages from client
    }

    async cleanup() {
        // Cleanup when connection closes
    }
}

Registering a WebSocket route

ctx.Connection('my_ws', '/ws/my-channel', MyWsHandler);

Using WebSocket events

// Listen for new subscriptions
ctx.on('subscription/enable', (channel, h, privileged, onDispose) => {
    // h is the ConnectionHandler instance
    // onDispose(callback) registers cleanup for this subscription
    onDispose(() => { /* cleanup */ });
});

WebSocket lifecycle

handler/create events fire
Permission checker runs
_prepare() → prepare() called
Subscriptions registered via @subscribe decorator
Connection enters active state
message() handler receives incoming messages
cleanup() runs on disconnect/error

SSE (Server-Sent Events) mode

ConnectionHandler also supports SSE when accessed via HTTP (not WebSocket upgrade):

// SSE auto-detected when client connects via HTTP but handler is ConnectionHandler
// this.conn.send(data) works for both WebSocket and SSE

10. Handler Inheritance Patterns

Handlers support class inheritance for sharing logic:

// Base handler: loads shared data
class ContestDetailBaseHandler extends Handler {
    tdoc?: Tdoc;
    tsdoc?: any;

    @param('tid', Types.ObjectId, true)
    async __prepare(domainId: string, tid: ObjectId) {
        if (!tid) return;
        [this.tdoc, this.tsdoc] = await Promise.all([
            contest.get(domainId, tid),
            contest.getStatus(domainId, tid, this.user._id),
        ]);
    }
}

// Sub handler: adds specific logic
class ContestScoreboardHandler extends ContestDetailBaseHandler {
    @param('tid', Types.ObjectId)
    async prepare(domainId: string, tid: ObjectId) {
        // tdoc already loaded by __prepare
        if (!contest.canShowScoreboard.call(this, this.tdoc, true)) {
            throw new ContestNotLiveError(tid);
        }
    }

    @param('tid', Types.ObjectId)
    async get(domainId: string, tid: ObjectId) {
        this.response.template = 'contest_scoreboard.html';
        this.response.body = { tdoc: this.tdoc };
    }
}

Inheritance + prepare chain

When using inheritance, the three prepare layers map naturally:

__prepare in the base class — load shared data (e.g., tdoc)
_prepare in intermediate class — load secondary data (e.g., pdoc)
prepare in the leaf class — permission checks, final setup

Each layer uses @param decorators independently. The framework collects all @param decorators across the inheritance chain for each method name.

11. Common Patterns

CRUD Handler (combines GET + multiple POST operations)

class ItemHandler extends Handler {
    item?: ItemDoc;

    @param('id', Types.ObjectId, true)
    async _prepare(domainId: string, id?: ObjectId) {
        if (id) {
            this.item = await ItemModel.get(domainId, id);
            if (!this.item) throw new NotFoundError(id);
        }
    }

    // List items
    @param('page', Types.PositiveInt, true)
    async get(domainId: string, page = 1) {
        const [items, count] = await this.ctx.db.paginate(
            ItemModel.getMulti(domainId), page, 20,
        );
        this.response.template = 'item_list.html';
        this.response.body = { items, count, page };
    }

    // Create item (POST without operation)
    @param('title', Types.Title)
    @param('content', Types.Content)
    async post(domainId: string, title: string, content: string) {
        this.checkPerm(PERM.PERM_CREATE_PROBLEM);
        await this.limitRate('create_item', 60, 10);
        const id = await ItemModel.add(domainId, title, content, this.user._id);
        this.response.redirect = this.url('item_detail', { id });
    }

    // Edit (POST with operation=edit)
    @param('id', Types.ObjectId)
    @param('title', Types.Title)
    async postEdit(domainId: string, id: ObjectId, title: string) {
        if (!this.user.own(this.item!)) this.checkPerm(PERM.PERM_EDIT_PROBLEM);
        await ItemModel.edit(domainId, id, { title });
        this.back();
    }

    // Delete (POST with operation=delete)
    @param('id', Types.ObjectId)
    async postDelete(domainId: string, id: ObjectId) {
        if (!this.user.own(this.item!)) this.checkPerm(PERM.PERM_EDIT_PROBLEM);
        await ItemModel.del(domainId, id);
        this.response.redirect = this.url('item_list');
    }
}

// Register once, handles GET + POST + operations
ctx.Route('item_list', '/item', ItemHandler);
ctx.Route('item_detail', '/item/:id', ItemHandler);

JSON API Handler

class ApiHandler extends Handler {
    @param('query', Types.String)
    async get(domainId: string, query: string) {
        const results = await searchItems(domainId, query);
        this.response.body = { results };  // No template = JSON response
    }
}

hydro-plugin-handler

More from this repository

More from this repository

Hydro Plugin Development: Handler & Route System

1. Route Registration

Parameters

Permission checker variants

Route name conventions

2. Handler Lifecycle (Complete Steps)

Error handling (any step throws)

Control flow

The three prepare layers

3. HTTP Method Handling

GET handler

POST handler (simple)

POST with operation mechanism

The all() method

4. Parameter Decorators

Type specifications

Optional parameters

Validation + Convert

The domainId convention

5. Security Decorator: @requireSudo

How it works

Usage

When to use @requireSudo

Session behavior

6. Response Building

Render a template (HTML page)

Return JSON (API endpoint)

Redirect

Back to referer

File download

Set response status

Set response headers

Available response properties

7. Handler Context Properties

Common handler methods

8. The after() Method

9. WebSocket (ConnectionHandler)

Basic WebSocket handler

Registering a WebSocket route

Using WebSocket events

WebSocket lifecycle

SSE (Server-Sent Events) mode

10. Handler Inheritance Patterns

Inheritance + prepare chain

11. Common Patterns

CRUD Handler (combines GET + multiple POST operations)

JSON API Handler

Hydro Plugin Development: Handler & Route System

1. Route Registration

Parameters

Permission checker variants

Route name conventions

2. Handler Lifecycle (Complete Steps)

Error handling (any step throws)

Control flow

The three prepare layers

3. HTTP Method Handling

GET handler

POST handler (simple)

POST with operation mechanism

The all() method

4. Parameter Decorators

Type specifications

Optional parameters

Validation + Convert

The domainId convention

5. Security Decorator: @requireSudo

How it works

Usage

When to use @requireSudo

Session behavior

6. Response Building

Render a template (HTML page)

Return JSON (API endpoint)

Redirect

Back to referer

File download

The `all()` method

5. Security Decorator: `@requireSudo`

When to use `@requireSudo`

8. The `after()` Method

The `all()` method

5. Security Decorator: `@requireSudo`

When to use `@requireSudo`

8. The `after()` Method