@alliage/webserver NPM

Alliage Webserver

Add web server capabilities to your Alliage application with automatic controller registration and middleware support.

Dependencies

@alliage/config-loader - Configuration management
@alliage/module-installer - Module installation utilities
@alliage/process-manager - Process management

Installation

yarn add @alliage/webserver

Or with npm:

npm install @alliage/webserver

Registration

If you've already installed @alliage/module-installer, simply run:

npx alliage-scripts install @alliage/webserver

Otherwise, update your alliage-modules.json file by adding:

{
  // ... other modules
  "@alliage/webserver": {
    "module": "@alliage/webserver",
    "deps": [
      "@alliage/config-loader",
      "@alliage/module-installer", 
      "@alliage/process-manager"
    ],
    "envs": []
  }
}

Usage

This module provides a web server process that can handle HTTP requests through controllers and process them through middlewares. It uses an adapter pattern to support different HTTP server implementations.

Configuration

Upon installation, a config/webserver.yaml file will be created with default settings:

port: 8080
host: localhost
isSecured: false
# privateKey: ""
# certificate: ""

Configuration Options

port (number, required): The port number for the web server
host (string, optional): The hostname to bind to (defaults to localhost)
isSecured (boolean): Whether to use HTTPS
privateKey (string, required if isSecured is true): Content of the private key file for HTTPS
certificate (string, required if isSecured is true): Content of the certificate file for HTTPS

Adapters

The webserver module requires an adapter to handle the actual HTTP server implementation. Adapters translate between the Alliage webserver abstractions and specific HTTP server libraries.

Available Adapters

@alliage/webserver-express: Express.js adapter for Node.js applications

Installing an Adapter

# Install the Express adapter
yarn add @alliage/webserver-express

# Register it in your alliage-modules.json
{
  "@alliage/webserver-express": {
    "module": "@alliage/webserver-express",
    "deps": ["@alliage/webserver"],
    "envs": []
  }
}

Defining Controllers

Controllers handle HTTP requests and define routes. They must extend AbstractController and use route decorators.

import {
  AbstractController,
  AbstractRequest,
  AbstractResponse,
  Get,
  Post,
  Put,
  Delete
} from '@alliage/webserver';
import { Service } from '@alliage/service-loader';

interface CreateUserBody {
  name: string;
  email: string;
}

@Service('user-controller')
export default class UserController extends AbstractController {
  @Get('/users')
  async listUsers(request: AbstractRequest, response: AbstractResponse) {
    // Fetch users from database
    const users = await this.userService.findAll();
    response.setBody({ users });
  }

  @Get('/users/:id')
  async getUser(request: AbstractRequest, response: AbstractResponse) {
    const { id } = request.getParams();
    const user = await this.userService.findById(id);
    
    if (!user) {
      response.setStatus(404).setBody({ error: 'User not found' });
      return;
    }
    
    response.setBody({ user });
  }

  @Post('/users')
  async createUser(
    request: AbstractRequest<unknown, unknown, CreateUserBody>,
    response: AbstractResponse
  ) {
    const { name, email } = request.getBody();
    const user = await this.userService.create({ name, email });
    response.setStatus(201).setBody({ user });
  }

  @Put('/users/:id')
  async updateUser(
    request: AbstractRequest<unknown, unknown, Partial<CreateUserBody>>,
    response: AbstractResponse
  ) {
    const { id } = request.getParams();
    const updates = request.getBody();
    const user = await this.userService.update(id, updates);
    response.setBody({ user });
  }

  @Delete('/users/:id')
  async deleteUser(request: AbstractRequest, response: AbstractResponse) {
    const { id } = request.getParams();
    await this.userService.delete(id);
    response.setStatus(204);
  }
}

Route Decorators

Available HTTP method decorators:

@Get(path) - Handle GET requests
@Post(path) - Handle POST requests
@Put(path) - Handle PUT requests
@Delete(path) - Handle DELETE requests
@Head(path) - Handle HEAD requests
@Options(path) - Handle OPTIONS requests
@Connect(path) - Handle CONNECT requests
@Trace(path) - Handle TRACE requests

Path parameters are supported using Express-style syntax: /users/:id, /posts/:postId/comments/:commentId

Defining Middlewares

Middlewares process requests before or after controllers. They must extend AbstractMiddleware.

Custom Middleware Example

import { 
  AbstractMiddleware, 
  REQUEST_PHASE, 
  Context 
} from '@alliage/webserver';
import { Service } from '@alliage/service-loader';

@Service('auth-middleware')
export default class AuthMiddleware extends AbstractMiddleware {
  getRequestPhase = () => REQUEST_PHASE.PRE_CONTROLLER;

  async apply(context: Context) {
    const request = context.getRequest();
    const response = context.getResponse();
    
    const authHeader = request.getHeaders().authorization;
    
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      response.setStatus(401).setBody({ error: 'Unauthorized' }).end();
      return;
    }
    
    const token = authHeader.substring(7);
    try {
      const user = await this.authService.validateToken(token);
      request.setExtraPayload('user', user);
    } catch (error) {
      response.setStatus(401).setBody({ error: 'Invalid token' }).end();
    }
  }
}

Middleware Ordering

Middlewares can specify their execution order relative to other middlewares:

import { 
  AbstractMiddleware, 
  REQUEST_PHASE, 
  Context 
} from '@alliage/webserver';
import { Service } from '@alliage/service-loader';

@Service('cors-middleware')
export default class CorsMiddleware extends AbstractMiddleware {
  // This middleware should run before AuthMiddleware
  applyBefore = () => [AuthMiddleware];
  
  // This middleware should run after LoggingMiddleware  
  applyAfter = () => [LoggingMiddleware];

  getRequestPhase = () => REQUEST_PHASE.PRE_CONTROLLER;

  apply(context: Context) {
    const response = context.getResponse();
    response.setHeader('Access-Control-Allow-Origin', '*');
    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  }
}

Request Phases

REQUEST_PHASE.PRE_CONTROLLER: Execute before controller actions
REQUEST_PHASE.POST_CONTROLLER: Execute after controller actions

Request and Response Objects

AbstractRequest

The request object provides access to HTTP request data:

// Get URL parameters
const { id } = request.getParams();

// Get query parameters  
const { page, limit } = request.getQuery();

// Get request body
const body = request.getBody();

// Get headers
const contentType = request.getHeaders()['content-type'];

// Get HTTP method
const method = request.getMethod();

// Get URL path
const path = request.getPath();

// Store/retrieve extra data
request.setExtraPayload('user', userData);
const user = request.getExtraPayload('user');

AbstractResponse

The response object allows you to build HTTP responses:

// Set response body
response.setBody({ message: 'Success' });

// Set status code
response.setStatus(201);

// Set headers
response.setHeader('Content-Type', 'application/json');

// Check if response is finished
if (!response.isFinished()) {
  response.setBody({ error: 'Something went wrong' });
}

// End the response (usually done automatically)
response.end();

Running the Web Server

Start the web server using the process manager:

# Start with default configuration
$ npx alliage-scripts start web

# Start on a specific port
$ npx alliage-scripts start web --port 3000

Integration with Service Loader

Controllers and middlewares are automatically discovered and registered when using @alliage/service-loader:

Place controllers in files matching the service loader patterns (e.g., src/controllers/**/*)
Export them as default exports with the @Service decorator
They will be automatically registered with the webserver

Events

The webserver module emits several events during the request lifecycle that you can listen to for logging, monitoring, or custom processing.