Architecting FeathersJS Service Hooks as a Unified Enforcement Boundary

The problem: Transport duplication in hybrid APIs

When building an API that supports both REST and real-time (WebSocket) clients, developers often duplicate validation, authorization, and side-effect logic across HTTP middleware and socket event handlers. This leads to "drift," where a security check updated for REST is forgotten for real-time clients.

The useful takeaway is to treat the Feathers service as the sole entry point and enforce all cross-cutting concerns within service hooks. Because hooks execute regardless of the transport used to trigger the service, you ensure identical behavior, security, and data integrity across all clients without branching your code.

Requirements for a unified service layer

A Feathers service provides a standardized interface (find, get, create, patch, remove). To maintain a clean architecture, the service layer must meet these requirements:

• Transport Agnosticism: The core business logic must not know if the request came from a GET request or a Socket.io event.
• Consistent Validation: Input data must be sanitized and validated against a schema before reaching the persistence layer.
• Centralized Authorization: Access control must be verified based on the authenticated user present in the request parameters.
• Reliable Side-Effects: Events (like sending an email or updating a cache) should trigger only after a successful database write.

The smallest suitable design: Hook Composition

The most efficient design is a thin service class paired with a sequence of composed hooks. In this model, the service method is reduced to a simple wrapper around a persistence adapter, while the hooks handle the "plumbing."

// Implementation example: Run in project root with node permissions
// Assumes Feathers v4/v5 pattern

class MessagesService {
  async create(data, params) {
    // Core service method: only handles persistence
    return this.adapter.create(data);
  }
  async find(params) {
    return this.adapter.find(params);
  }
}

const service = app.use('/messages', new MessagesService());

service.hooks({
  before: {
    create: [validateCreate, authorizeUser]
  },
  after: {
    create: [publishCreated]
  }
});

In this design, validateCreate is a before hook that inspects context.data and rejects the request with a BadRequest error if fields are missing. authorizeUser checks context.params.user for a valid session. Finally, publishCreated is an after hook that processes context.result to trigger external notifications.

Trust and data boundaries

The primary trust boundary is the transition from the Hook Layer to the Service Method. All data entering the system via data or params must be treated as untrusted.

• Input Boundary: Before hooks act as the firewall. No data should reach the adapter without passing through a validation hook.
• Parameter Boundary: The params object contains authentication data. This should be verified in a hook; the service method should assume that if it is being executed, the user has already been authorized.
• Persistence Boundary: The adapter is the final boundary. While hooks provide application-level validation, they do not replace database constraints (e.g., unique indexes) or ACID transactions.

Operational checks and verification

To ensure the boundary is working as intended, implement the following checks:

Check	Method	Expected Result
Transport Parity	Call create via REST and WebSocket with invalid data.	Both return identical error codes/messages.
Auth Enforcement	Call a protected service without a JWT.	Before hook rejects with Forbidden before adapter is called.
Hook Sequence	Log context.data in a before hook.	Data is present and unmodified before the service method runs.

Limitation: Hooks run in-process. If the Node.js process crashes after the service method completes but before the after-hook finishes, the side-effect (e.g., an email) will be lost.

Failure modes and design shifts

Understanding how hooks fail is critical for system reliability:

• Before Hook Failure: If a before hook throws an error, the service method and all subsequent hooks are skipped. This is the intended behavior for validation.
• After Hook Failure: An error in an after hook occurs after the database has been updated. This can lead to inconsistent state if the after-hook was responsible for a critical secondary update.
• Async Side-Effects: Unhandled promise rejections in after-hooks may not propagate back to the client, leading to "silent" failures.

When to change this design

This hook-based architecture is sufficient for most APIs, but you should migrate to a more robust pattern if:

1. Durability is required: If after-hooks perform critical tasks, replace them with an out-of-process message queue (e.g., RabbitMQ or BullMQ).
2. Distributed Transactions: If you need to update multiple services atomically, move logic from hooks into a dedicated "manager" service or use a database-level transaction.
3. Complex State Machines: If the sequence of hooks becomes too complex to reason about, move the logic into the service method using a Command pattern.