@uvrn/api 1.0.0

package/src/middleware/errorHandler.ts

@@ -0,0 +1,69 @@
+/**
+ * Global Error Handler
+ * Handles uncaught errors and formats error responses
+ */
+
+import { FastifyInstance, FastifyError, FastifyRequest, FastifyReply } from 'fastify';
+import { ErrorResponse } from '../types/api';
+
+/**
+ * Register global error handler
+ */
+export function registerErrorHandler(server: FastifyInstance): void {
+  server.setErrorHandler((error: FastifyError, request: FastifyRequest, reply: FastifyReply) => {
+    // Log the error
+    request.log.error({
+      err: error,
+      url: request.url,
+      method: request.method
+    }, 'Request error');
+
+    // Determine status code
+    const statusCode = error.statusCode || 500;
+
+    // Map error to code
+    let errorCode = 'INTERNAL_ERROR';
+    if (statusCode === 400) errorCode = 'BAD_REQUEST';
+    else if (statusCode === 404) errorCode = 'NOT_FOUND';
+    else if (statusCode === 415) errorCode = 'UNSUPPORTED_MEDIA_TYPE';
+    else if (statusCode === 429) errorCode = 'RATE_LIMIT_EXCEEDED';
+    else if (statusCode === 503) errorCode = 'SERVICE_UNAVAILABLE';
+
+    // Build error response
+    const errorResponse: ErrorResponse = {
+      error: {
+        code: errorCode,
+        message: error.message || 'An unexpected error occurred',
+        details: {
+          statusCode
+        }
+      }
+    };
+
+    // Don't expose internal error details in production
+    if (process.env.NODE_ENV !== 'production' && error.stack) {
+      errorResponse.error.details = {
+        ...errorResponse.error.details,
+        stack: error.stack
+      };
+    }
+
+    reply.code(statusCode).send(errorResponse);
+  });
+
+  // Handle 404 errors
+  server.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    const errorResponse: ErrorResponse = {
+      error: {
+        code: 'NOT_FOUND',
+        message: `Route ${request.method} ${request.url} not found`,
+        details: {
+          method: request.method,
+          url: request.url
+        }
+      }
+    };
+
+    reply.code(404).send(errorResponse);
+  });
+}

package/src/routes/delta.ts

@@ -0,0 +1,120 @@
+/**
+ * Delta Engine API Routes
+ * Endpoints for bundle processing, validation, and verification
+ */
+
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import {
+  DeltaBundle,
+  DeltaReceipt,
+  runDeltaEngine,
+  validateBundle,
+  verifyReceipt
+} from '@uvrn/core';
+import { ErrorResponse, ValidationResponse } from '../types/api';
+
+/**
+ * Register delta engine routes
+ */
+export async function registerDeltaRoutes(server: FastifyInstance): Promise<void> {
+  // POST /api/v1/delta/run - Execute engine on bundle
+  server.post<{
+    Body: DeltaBundle;
+    Reply: DeltaReceipt | ErrorResponse;
+  }>('/api/v1/delta/run', async (request: FastifyRequest<{ Body: DeltaBundle }>, reply: FastifyReply) => {
+    try {
+      const bundle = request.body;
+
+      // Validate bundle schema
+      const validation = validateBundle(bundle);
+      if (!validation.valid) {
+        return reply.code(400).send({
+          error: {
+            code: 'INVALID_BUNDLE',
+            message: 'Bundle validation failed',
+            details: { validationError: validation.error }
+          }
+        });
+      }
+
+      // Execute engine
+      const receipt = runDeltaEngine(bundle);
+
+      return reply.code(200).send(receipt);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      request.log.error({ error: errorMessage }, 'Engine execution failed');
+
+      return reply.code(500).send({
+        error: {
+          code: 'ENGINE_ERROR',
+          message: 'Failed to process bundle',
+          details: { error: errorMessage }
+        }
+      });
+    }
+  });
+
+  // POST /api/v1/delta/validate - Validate bundle schema
+  server.post<{
+    Body: DeltaBundle;
+    Reply: ValidationResponse | ErrorResponse;
+  }>('/api/v1/delta/validate', async (request: FastifyRequest<{ Body: DeltaBundle }>, reply: FastifyReply) => {
+    try {
+      const bundle = request.body;
+      const validation = validateBundle(bundle);
+
+      if (!validation.valid) {
+        return reply.code(200).send({
+          valid: false,
+          errors: [
+            {
+              field: 'bundle',
+              message: validation.error || 'Validation failed'
+            }
+          ]
+        });
+      }
+
+      return reply.code(200).send({ valid: true });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      request.log.error({ error: errorMessage }, 'Validation failed');
+
+      return reply.code(500).send({
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Failed to validate bundle',
+          details: { error: errorMessage }
+        }
+      });
+    }
+  });
+
+  // POST /api/v1/delta/verify - Verify receipt replay
+  server.post<{
+    Body: DeltaReceipt;
+    Reply: { verified: boolean; recomputedHash?: string } | ErrorResponse;
+  }>('/api/v1/delta/verify', async (request: FastifyRequest<{ Body: DeltaReceipt }>, reply: FastifyReply) => {
+    try {
+      const receipt = request.body;
+      const verifyResult = verifyReceipt(receipt);
+
+      return reply.code(200).send({
+        verified: verifyResult.verified,
+        recomputedHash: verifyResult.recomputedHash
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      request.log.error({ error: errorMessage }, 'Verification failed');
+
+      return reply.code(500).send({
+        error: {
+          code: 'VERIFICATION_ERROR',
+          message: 'Failed to verify receipt',
+          details: { error: errorMessage }
+        }
+      });
+    }
+  });
+}

package/src/routes/health.ts

@@ -0,0 +1,65 @@
+/**
+ * Health and Version Routes
+ * System status and version information endpoints
+ */
+
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { HealthResponse, VersionResponse } from '../types/api';
+
+const SERVER_START_TIME = Date.now();
+const API_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '1.0';
+
+/**
+ * Register health and version routes
+ */
+export async function registerHealthRoutes(server: FastifyInstance): Promise<void> {
+  // GET /api/v1/health - Health check endpoint
+  server.get<{
+    Reply: HealthResponse;
+  }>('/api/v1/health', async (_request: FastifyRequest, reply: FastifyReply) => {
+    const uptime = Date.now() - SERVER_START_TIME;
+
+    // Check if engine is available by attempting to import it
+    let engineAvailable = true;
+    try {
+      require('@uvrn/core');
+    } catch {
+      engineAvailable = false;
+    }
+
+    const health: HealthResponse = {
+      status: engineAvailable ? 'healthy' : 'unhealthy',
+      uptime,
+      version: API_VERSION,
+      engine: {
+        available: engineAvailable
+      },
+      timestamp: new Date().toISOString()
+    };
+
+    const statusCode = engineAvailable ? 200 : 503;
+    return reply.code(statusCode).send(health);
+  });
+
+  // GET /api/v1/version - Version information
+  server.get<{
+    Reply: VersionResponse;
+  }>('/api/v1/version', async (_request: FastifyRequest, reply: FastifyReply) => {
+    let engineVersion = 'unknown';
+    try {
+      const enginePkg = require('@uvrn/core/package.json');
+      engineVersion = enginePkg.version;
+    } catch {
+      // Engine version not available
+    }
+
+    const version: VersionResponse = {
+      apiVersion: API_VERSION,
+      engineVersion,
+      protocolVersion: PROTOCOL_VERSION
+    };
+
+    return reply.code(200).send(version);
+  });
+}

package/src/server.ts

@@ -0,0 +1,139 @@
+/**
+ * Delta Engine API Server
+ * Fastify-based REST API for bundle processing
+ */
+
+import Fastify, { FastifyInstance } from 'fastify';
+import cors from '@fastify/cors';
+import helmet from '@fastify/helmet';
+import rateLimit from '@fastify/rate-limit';
+import { loadConfig } from './config/loader';
+import { ServerConfig } from './config/types';
+import { registerDeltaRoutes } from './routes/delta';
+import { registerHealthRoutes } from './routes/health';
+import { registerErrorHandler } from './middleware/errorHandler';
+
+/**
+ * Create and configure Fastify server instance
+ */
+export async function createServer(config?: ServerConfig): Promise<FastifyInstance> {
+  // Load configuration
+  const serverConfig = config || loadConfig();
+
+  // Create Fastify instance with logging
+  const server = Fastify({
+    logger: {
+      level: serverConfig.logLevel,
+      transport: serverConfig.nodeEnv === 'development' ? {
+        target: 'pino-pretty',
+        options: {
+          translateTime: 'HH:MM:ss Z',
+          ignore: 'pid,hostname'
+        }
+      } : undefined
+    }
+  });
+
+  // Register plugins
+  await server.register(helmet, {
+    contentSecurityPolicy: serverConfig.nodeEnv === 'production' ? undefined : false
+  });
+
+  await server.register(cors, {
+    origin: serverConfig.corsOrigins,
+    credentials: true
+  });
+
+  await server.register(rateLimit, {
+    max: serverConfig.rateLimitMax,
+    timeWindow: serverConfig.rateLimitTimeWindow,
+    errorResponseBuilder: () => ({
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Too many requests, please try again later',
+        details: {
+          rateLimitMax: serverConfig.rateLimitMax,
+          timeWindow: serverConfig.rateLimitTimeWindow
+        }
+      }
+    })
+  });
+
+  // Add request logging hook
+  server.addHook('onRequest', async (request, _reply) => {
+    request.log.info({
+      url: request.url,
+      method: request.method,
+      ip: request.ip
+    }, 'Incoming request');
+  });
+
+  server.addHook('onResponse', async (request, reply) => {
+    request.log.info({
+      url: request.url,
+      method: request.method,
+      statusCode: reply.statusCode,
+      responseTime: reply.elapsedTime
+    }, 'Request completed');
+  });
+
+  // Validate content-type for POST requests
+  server.addHook('preHandler', async (request, reply) => {
+    if (request.method === 'POST' && request.url.startsWith('/api/v1/delta/')) {
+      const contentType = request.headers['content-type'];
+      if (!contentType || !contentType.includes('application/json')) {
+        return reply.code(415).send({
+          error: {
+            code: 'UNSUPPORTED_MEDIA_TYPE',
+            message: 'Content-Type must be application/json',
+            details: {
+              receivedContentType: contentType || 'none'
+            }
+          }
+        });
+      }
+    }
+  });
+
+  // Register routes
+  await registerHealthRoutes(server);
+  await registerDeltaRoutes(server);
+
+  // Register error handler (must be last)
+  registerErrorHandler(server);
+
+  return server;
+}
+
+/**
+ * Start the server
+ */
+export async function startServer(config?: ServerConfig): Promise<FastifyInstance> {
+  const serverConfig = config || loadConfig();
+  const server = await createServer(serverConfig);
+
+  try {
+    await server.listen({
+      port: serverConfig.port,
+      host: serverConfig.host
+    });
+
+    server.log.info(`🚀 Delta Engine API server running at http://${serverConfig.host}:${serverConfig.port}`);
+    server.log.info(`📊 Health check: http://${serverConfig.host}:${serverConfig.port}/api/v1/health`);
+    server.log.info(`📦 Environment: ${serverConfig.nodeEnv}`);
+    server.log.info(`🔒 Rate limit: ${serverConfig.rateLimitMax} requests per ${serverConfig.rateLimitTimeWindow}`);
+
+    return server;
+  } catch (error) {
+    server.log.error(error);
+    throw error;
+  }
+}
+
+// Start server if run directly
+if (require.main === module) {
+  startServer().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  });
+}

package/src/types/api.ts

@@ -0,0 +1,35 @@
+/**
+ * API-specific type definitions
+ */
+
+export interface ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+export interface HealthResponse {
+  status: 'healthy' | 'unhealthy';
+  uptime: number;
+  version: string;
+  engine: {
+    available: boolean;
+  };
+  timestamp: string;
+}
+
+export interface VersionResponse {
+  apiVersion: string;
+  engineVersion: string;
+  protocolVersion: string;
+}
+
+export interface ValidationResponse {
+  valid: boolean;
+  errors?: Array<{
+    field: string;
+    message: string;
+  }>;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}