@swoft/middleware

Shared Express middleware for Swoft microservices. Provides consistent behavior across all backend services.

Installation

pnpm add @swoft/middleware

Response Metadata Middleware

Adds standardized metadata to all JSON responses for debugging, tracing, and monitoring.

Basic Usage

import express from 'express';
import { createResponseMetadataMiddleware } from '@swoft/middleware';

const app = express();

app.use(
  createResponseMetadataMiddleware({
    serviceName: 'my-service',
    version: '1.0.0',
  })
);

Advanced Configuration

app.use(
  createResponseMetadataMiddleware({
    serviceName: '@swoft/collaboration-backend',
    version: '2.0.0',
    includeDatabase: true,
    databaseType: 'mongodb',
    getDatabaseStatus: () => db.isConnected(),
    getPort: () => parseInt(process.env.PORT || '4004'),
    enableRequestIdHeader: true,
  })
);

Response Structure

All responses will be wrapped with metadata:

{
  "data": {
    /* original response */
  },
  "metadata": {
    "service": "@swoft/collaboration-backend",
    "environment": "development",
    "database": {
      "type": "mongodb",
      "url": "mongodb://localhost:27017/swoft",
      "connected": true
    },
    "server": {
      "hostname": "dev-machine",
      "port": 4004,
      "pid": 12345
    },
    "timestamp": "2025-01-25T16:30:00.000Z",
    "version": "2.0.0",
    "responseTimeMs": 45,
    "requestId": "1753460000000-abc123def"
  }
}

MCP Tool Integration

For MCP tools that call backend services:

import { addMCPMetadata, extractMetadata } from '@swoft/middleware';

// In your MCP tool
const backendResponse = await fetch('/api/gtd/tasks');
const responseWithMCPMetadata = addMCPMetadata(backendResponse, {
  tool: 'gtd_project_list',
  version: '1.0.0',
  processingTimeMs: 5,
});

Production Mode

In production (NODE_ENV=production):

• Database information is hidden
• Server hostname and PID are masked
• Less sensitive metadata is included

Environment Variables

• NODE_ENV - Controls production mode behavior
• API_VERSION - Default version if not specified
• PORT - Default port if getPort not provided
• MONGODB_URI - Database connection string (password sanitized)

Future Middleware

This package will grow to include:

• Error handling middleware
• Request validation middleware
• Rate limiting middleware
• Authentication middleware
• CORS configuration

Contributing

When adding new middleware:

1. Create a new directory under src/
2. Export from src/index.ts
3. Add documentation to this README
4. Include TypeScript types