Appendix A: API Reference

Core Classes

HypermodernServer

The main server class that handles multi-protocol communication.

class HypermodernServer {
  // Constructor
  HypermodernServer({
    ServerConfig? config,
    ModuleContainer? container,
  });
  
  // Configuration
  void configure(ServerConfig config);
  void configureTcp(TcpServerConfig config);
  void configureHttp(HttpServerConfig config);
  void configureWebSocket(WebSocketServerConfig config);
  
  // Lifecycle
  Future<void> listen({
    int? httpPort,
    int? wsPort,
    int? tcpPort,
    String? bindAddress,
  });
  Future<void> stop();
  Future<void> restart();
  
  // Endpoint Registration
  void registerEndpoint<TRequest, TResponse>(
    String name,
    Future<TResponse> Function(TRequest) handler,
  );
  
  void registerStreamingEndpoint<TRequest, TResponse>(
    String name,
    Stream<TResponse> Function(TRequest) handler,
  );
  
  void registerBidirectionalStreamingEndpoint<TRequest, TResponse>(
    String name,
    Future<void> Function(
      Stream<TRequest> incoming,
      StreamSink<TResponse> outgoing,
    ) handler,
  );
  
  // Middleware
  MiddlewareStack get middleware;
  void addMiddleware(Middleware middleware);
  void removeMiddleware(Middleware middleware);
  
  // Module Management
  Future<void> installModule(HypermodernModule module);
  Future<void> uninstallModule(String moduleName);
  List<HypermodernModule> get installedModules;
  
  // Events
  Stream<ServerEvent> get events;
  
  // Metrics
  ServerMetrics get metrics;
}

HypermodernClient

The client class for connecting to Hypermodern servers.

class HypermodernClient {
  // Constructors
  HypermodernClient(String url, {ClientConfig? config});
  HypermodernClient.http(String url, {ClientConfig? config});
  HypermodernClient.websocket(String url, {ClientConfig? config});
  HypermodernClient.tcp(String url, {ClientConfig? config});
  
  // Connection Management
  Future<void> connect();
  Future<void> disconnect();
  Future<void> reconnect();
  bool get isConnected;
  
  // Authentication
  void setAuthToken(String token);
  void setAuthProvider(AuthProvider provider);
  void clearAuth();
  
  // Request/Response
  Future<TResponse> request<TResponse>(
    String endpoint,
    dynamic request, {
    Duration? timeout,
    CancellationToken? cancellationToken,
  });
  
  // Streaming
  Stream<TResponse> stream<TResponse>(
    String endpoint,
    dynamic request,
  );
  
  StreamController<TRequest> getStreamController<TRequest>(String endpoint);
  
  // Events
  Stream<ClientEvent> get events;
  Stream<ConnectionState> get connectionState;
  
  // Configuration
  ClientConfig get config;
  void updateConfig(ClientConfig config);
}

Database

Database abstraction layer for ORM operations.

class Database {
  // Constructor
  Database(ConnectionPool pool);
  
  // Query Operations
  Future<List<Map<String, dynamic>>> query(
    String sql, [
    List<dynamic>? parameters,
  ]);
  
  Future<void> execute(
    String sql, [
    List<dynamic>? parameters,
  ]);
  
  Future<PreparedStatement> prepare(String sql);
  
  // Transactions
  Future<T> transaction<T>(
    Future<T> Function(Transaction) callback,
  );
  
  // Connection Management
  Future<void> close();
  ConnectionPoolStats get poolStats;
  
  // Migration Support
  Future<void> runMigrations(List<Migration> migrations);
  Future<List<String>> getExecutedMigrations();
}

Configuration Classes

ServerConfig

class ServerConfig {
  final int httpPort;
  final int wsPort;
  final int tcpPort;
  final String bindAddress;
  final int maxConnections;
  final Duration requestTimeout;
  final Duration keepAliveTimeout;
  final bool corsEnabled;
  final List<String> corsOrigins;
  final bool rateLimitEnabled;
  final int rateLimitRequests;
  final Duration rateLimitWindow;
  final LogLevel logLevel;
  final bool metricsEnabled;
  
  const ServerConfig({
    this.httpPort = 8080,
    this.wsPort = 8082,
    this.tcpPort = 8081,
    this.bindAddress = '0.0.0.0',
    this.maxConnections = 1000,
    this.requestTimeout = const Duration(seconds: 30),
    this.keepAliveTimeout = const Duration(seconds: 60),
    this.corsEnabled = false,
    this.corsOrigins = const [],
    this.rateLimitEnabled = false,
    this.rateLimitRequests = 100,
    this.rateLimitWindow = const Duration(minutes: 1),
    this.logLevel = LogLevel.info,
    this.metricsEnabled = false,
  });
}

ClientConfig

class ClientConfig {
  final Duration connectionTimeout;
  final Duration requestTimeout;
  final int maxRetries;
  final Duration retryDelay;
  final double retryBackoffMultiplier;
  final bool autoReconnect;
  final int reconnectAttempts;
  final Duration reconnectDelay;
  final bool binaryMode;
  final bool compressionEnabled;
  final bool keepAlive;
  final bool validateCertificates;
  final Map<String, String> customHeaders;
  
  const ClientConfig({
    this.connectionTimeout = const Duration(seconds: 10),
    this.requestTimeout = const Duration(seconds: 30),
    this.maxRetries = 3,
    this.retryDelay = const Duration(seconds: 1),
    this.retryBackoffMultiplier = 2.0,
    this.autoReconnect = true,
    this.reconnectAttempts = 5,
    this.reconnectDelay = const Duration(seconds: 2),
    this.binaryMode = true,
    this.compressionEnabled = true,
    this.keepAlive = true,
    this.validateCertificates = true,
    this.customHeaders = const {},
  });
}

Middleware Classes

Middleware Interface

abstract class Middleware {
  Future<dynamic> handle(
    dynamic request,
    Future<dynamic> Function(dynamic) next,
  );
}

Built-in Middleware

AuthenticationMiddleware

class AuthenticationMiddleware implements Middleware {
  AuthenticationMiddleware({
    required JWTService jwtService,
    required TokenBlacklistService blacklistService,
    Set<String> publicEndpoints = const {},
    Set<String> optionalAuthEndpoints = const {},
  });
  
  @override
  Future<dynamic> handle(dynamic request, Future<dynamic> Function(dynamic) next);
}

RateLimitMiddleware

class RateLimitMiddleware implements Middleware {
  RateLimitMiddleware({
    required RateLimiter rateLimiter,
    Map<String, RateLimit> endpointLimits = const {},
    RateLimit defaultLimit = const RateLimit(requests: 100, window: Duration(minutes: 1)),
  });
  
  @override
  Future<dynamic> handle(dynamic request, Future<dynamic> Function(dynamic) next);
}

CORSMiddleware

class CORSMiddleware implements Middleware {
  CORSMiddleware({
    List<String> allowedOrigins = const ['*'],
    List<String> allowedMethods = const ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    List<String> allowedHeaders = const ['Content-Type', 'Authorization'],
    bool allowCredentials = false,
    Duration maxAge = const Duration(hours: 24),
  });
  
  @override
  Future<dynamic> handle(dynamic request, Future<dynamic> Function(dynamic) next);
}

Module System

HypermodernModule

abstract class HypermodernModule {
  ModuleManifest get manifest;
  List<Migration> get migrations => [];
  
  Future<void> register(ModuleContainer container);
  Future<void> boot(ModuleContainer container);
  
  Future<void> onInstall(ModuleContext context) async {}
  Future<void> onUninstall(ModuleContext context) async {}
  Future<void> onUpdate(ModuleContext context, String fromVersion) async {}
  Future<void> onConfigurationChange(
    ModuleContext context,
    Map<String, dynamic> oldConfig,
  ) async {}
}

ModuleManifest

class ModuleManifest {
  final String name;
  final String version;
  final String description;
  final String? author;
  final String? homepage;
  final String? license;
  final String hypermodernVersion;
  final Map<String, String> dependencies;
  final Map<String, String> devDependencies;
  final Map<String, List<String>> exports;
  final Map<String, dynamic> configuration;
  final List<String> permissions;
  final List<String> databaseTables;
  final List<String> tags;
  final List<String> keywords;
  
  ModuleManifest({
    required this.name,
    required this.version,
    required this.description,
    this.author,
    this.homepage,
    this.license,
    required this.hypermodernVersion,
    this.dependencies = const {},
    this.devDependencies = const {},
    this.exports = const {},
    this.configuration = const {},
    this.permissions = const [],
    this.databaseTables = const [],
    this.tags = const [],
    this.keywords = const [],
  });
  
  factory ModuleManifest.fromJson(Map<String, dynamic> json);
  Map<String, dynamic> toJson();
}

Exception Classes

Core Exceptions

class HypermodernException implements Exception {
  final String message;
  final String? code;
  final Map<String, dynamic>? details;
  
  HypermodernException(this.message, {this.code, this.details});
  
  @override
  String toString() => 'HypermodernException: $message';
}

class ValidationException extends HypermodernException {
  final Map<String, String> fieldErrors;
  
  ValidationException(
    String message, {
    this.fieldErrors = const {},
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code, details: details);
}

class NotFoundException extends HypermodernException {
  NotFoundException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'NOT_FOUND', details: details);
}

class UnauthorizedException extends HypermodernException {
  UnauthorizedException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'UNAUTHORIZED', details: details);
}

class ForbiddenException extends HypermodernException {
  ForbiddenException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'FORBIDDEN', details: details);
}

class ConflictException extends HypermodernException {
  ConflictException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'CONFLICT', details: details);
}

class RateLimitExceededException extends HypermodernException {
  final int retryAfter;
  
  RateLimitExceededException(
    String message, {
    required this.retryAfter,
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'RATE_LIMIT_EXCEEDED', details: details);
}

class ServerException extends HypermodernException {
  final int statusCode;
  
  ServerException(
    String message, {
    this.statusCode = 500,
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'SERVER_ERROR', details: details);
}

Network Exceptions

class NetworkException extends HypermodernException {
  NetworkException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'NETWORK_ERROR', details: details);
}

class TimeoutException extends NetworkException {
  final Duration timeout;
  
  TimeoutException(
    String message, {
    required this.timeout,
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'TIMEOUT', details: details);
}

class ConnectionException extends NetworkException {
  ConnectionException(
    String message, {
    String? code,
    Map<String, dynamic>? details,
  }) : super(message, code: code ?? 'CONNECTION_ERROR', details: details);
}

Utility Classes

Logger

class Logger {
  static Logger get instance => _instance;
  static Logger _instance = Logger._();
  
  Logger._();
  
  void debug(String message, {dynamic error, Map<String, dynamic>? extra});
  void info(String message, {dynamic error, Map<String, dynamic>? extra});
  void warning(String message, {dynamic error, Map<String, dynamic>? extra});
  void error(String message, {dynamic error, Map<String, dynamic>? extra});
  void critical(String message, {dynamic error, Map<String, dynamic>? extra});
  
  void setLevel(LogLevel level);
  void addHandler(LogHandler handler);
  void removeHandler(LogHandler handler);
}

enum LogLevel {
  debug,
  info,
  warning,
  error,
  critical,
}

Metrics

class MetricsCollector {
  void recordRequest({
    required String route,
    required String method,
    required int statusCode,
    required Duration duration,
    String? backendService,
  });
  
  void recordError({
    required String route,
    required String method,
    required String error,
    required Duration duration,
  });
  
  void incrementCounter(String name, {Map<String, String>? labels});
  void recordGauge(String name, double value, {Map<String, String>? labels});
  void recordHistogram(String name, double value, {Map<String, String>? labels});
  
  Map<String, dynamic> getMetrics();
  void reset();
}

Version

class Version implements Comparable<Version> {
  final int major;
  final int minor;
  final int patch;
  final String? preRelease;
  final String? build;
  
  Version(this.major, this.minor, this.patch, {this.preRelease, this.build});
  
  factory Version.parse(String version);
  
  @override
  int compareTo(Version other);
  
  @override
  String toString();
  
  bool operator >(Version other);
  bool operator <(Version other);
  bool operator >=(Version other);
  bool operator <=(Version other);
}

Constants

Protocol Types

class ProtocolType {
  static const String http = 'http';
  static const String websocket = 'websocket';
  static const String tcp = 'tcp';
}

Content Types

class ContentType {
  static const String json = 'application/json';
  static const String binary = 'application/x-hypermodern-binary';
  static const String text = 'text/plain';
  static const String html = 'text/html';
}

Status Codes

class StatusCode {
  // Success
  static const int ok = 200;
  static const int created = 201;
  static const int accepted = 202;
  static const int noContent = 204;
  
  // Client Errors
  static const int badRequest = 400;
  static const int unauthorized = 401;
  static const int forbidden = 403;
  static const int notFound = 404;
  static const int conflict = 409;
  static const int unprocessableEntity = 422;
  static const int tooManyRequests = 429;
  
  // Server Errors
  static const int internalServerError = 500;
  static const int badGateway = 502;
  static const int serviceUnavailable = 503;
  static const int gatewayTimeout = 504;
}

Type Definitions

Function Types

typedef RequestHandler<TRequest, TResponse> = Future<TResponse> Function(TRequest request);
typedef StreamingHandler<TRequest, TResponse> = Stream<TResponse> Function(TRequest request);
typedef MiddlewareHandler = Future<dynamic> Function(dynamic request, Future<dynamic> Function(dynamic) next);
typedef ErrorHandler = Future<dynamic> Function(dynamic error, dynamic request);

Callback Types

typedef ConnectionCallback = void Function();
typedef DisconnectionCallback = void Function();
typedef ErrorCallback = void Function(dynamic error);
typedef MessageCallback<T> = void Function(T message);

This API reference provides a comprehensive overview of the core Hypermodern classes, methods, and types. Use this as a quick reference when developing with the platform.