@owlmeans/server-context 0.1.2 → 0.1.4

package/README.md

@@ -1,516 +1,63 @@
 # @owlmeans/server-context
 
-Server-side context and dependency injection system for OwlMeans Common applications. This package extends the base OwlMeans context system with server-specific functionality, configuration management, and authentication capabilities for building secure backend services.
+Server-side context factory with file-based config, trusted keys, and Ed25519 guard pre-wired.
 
 ## Overview
 
-The `@owlmeans/server-context` package provides server-specific extensions to the OwlMeans context system, offering:
-
-- **Server Context Management**: Enhanced context with server-specific capabilities
-- **Configuration Integration**: Built-in configuration resource management
-- **Authentication Guards**: Pre-configured Ed25519 authentication guards
-- **Middleware System**: Server-optimized middleware for request processing
-- **Service Registration**: Streamlined service registration for server components
-- **File Configuration**: File-based configuration reading capabilities
-- **Security Defaults**: Secure-by-default configuration for production servers
+- `makeServerContext()` creates a context with file config reader, `PLUGINS` resource, and trusted key management
+- Extends `BasicContext` with `ServerContext` which includes API server and auth service append points
+- The `config` helper re-exported here configures a `ServerConfig` with `port`, `security`, etc.
+- Typically accessed through `@owlmeans/server-app`'s `makeContext`, which calls this internally
 
 ## Installation
 
 ```bash
-npm install @owlmeans/server-context
-```
-
-## Core Concepts
-
-### Server Context
-
-The `ServerContext` extends the basic OwlMeans context with server-specific functionality, including configuration resource management and enhanced service capabilities.
-
-### Server Configuration
-
-The `ServerConfig` combines server and client configuration options, providing a unified configuration structure for fullstack applications.
-
-### Security Integration
-
-Built-in integration with authentication guards and middleware for secure service-to-service communication.
-
-## API Reference
-
-### Types
-
-#### `ServerConfig`
-Extended configuration interface for server applications.
-
-```typescript
-interface ServerConfig extends BasicServerConfig, BasicClientConfig {
-  services: Record<string, ServiceRoute>
-}
-```
-
-#### `ServerContext<C extends ServerConfig>`
-Enhanced context interface with server capabilities.
-
-```typescript
-interface ServerContext<C extends ServerConfig> extends BasicContext<C>, ConfigResourceAppend {
-  // Inherits all BasicContext functionality plus configuration resource management
-}
-```
-
-### Factory Functions
-
-#### `makeServerContext<C, T>(cfg: C): T`
-Creates a server context with enhanced capabilities.
-
-**Parameters:**
-- `cfg`: Server configuration object
-
-**Returns:** Configured server context instance
-
-**Features:**
-- Registers file configuration reader middleware
-- Adds configuration resource management
-- Sets up trusted entity resource
-- Configures plugin resource management
-- Registers Ed25519 authentication guard
-- Adds authentication middleware
-
-#### `config<C>(service: string, cfg?: Partial<C>): C`
-Creates a server configuration with default settings.
-
-**Parameters:**
-- `service`: Service name identifier
-- `cfg`: Optional partial configuration
-
-**Returns:** Complete server configuration
-
-## Usage Examples
-
-### Basic Server Setup
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-// Create server configuration
-const serverConfig = config('my-service', {
-  port: 3000,
-  host: 'localhost',
-  services: {
-    database: {
-      protocol: 'mongodb',
-      host: 'localhost',
-      port: 27017
-    }
-  }
-})
-
-// Create server context
-const context = makeServerContext(serverConfig)
-
-// Initialize the context
-await context.init()
-```
-
-### Configuration with Resources
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-const serverConfig = config('api-server', {
-  // Database configurations
-  dbs: [
-    {
-      service: 'mongo',
-      alias: 'primary',
-      host: 'localhost',
-      port: 27017,
-      schema: 'myapp'
-    }
-  ],
-  
-  // Trusted services for authentication
-  trusted: [
-    {
-      id: 'internal-service',
-      recordType: 'trusted-source',
-      name: 'Internal Service',
-      entityId: 'internal',
-      scopes: ['api:*']
-    }
-  ],
-  
-  // Service routes
-  services: {
-    'user-service': {
-      protocol: 'https',
-      host: 'user-service.internal',
-      port: 443
-    },
-    'auth-service': {
-      protocol: 'https', 
-      host: 'auth-service.internal',
-      port: 443
-    }
-  }
-})
-
-const context = makeServerContext(serverConfig)
-```
-
-### Service Registration
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-import { createDbService } from '@owlmeans/mongo'
-
-const context = makeServerContext(config('my-service'))
-
-// Register database service
-const dbService = createDbService('primary')
-context.registerService(dbService)
-
-// Register custom service
-const customService = {
-  alias: 'custom-logic',
-  initialized: false,
-  init: async () => {
-    console.log('Custom service initialized')
-    return true
-  }
-}
-context.registerService(customService)
-```
-
-### Authentication Setup
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-const serverConfig = config('secure-service', {
-  trusted: [
-    {
-      id: 'client-app',
-      recordType: 'trusted-source',
-      name: 'Client Application',
-      credential: 'base64-encoded-public-key',
-      scopes: ['read', 'write']
-    }
-  ]
-})
-
-const context = makeServerContext(serverConfig)
-
-// The Ed25519 guard is automatically registered
-// Authentication middleware is automatically added
-// Requests with valid signatures will be authenticated
-```
-
-### Custom Middleware Registration
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-import { MiddlewareType, MiddlewareStage } from '@owlmeans/context'
-
-const context = makeServerContext(config('my-service'))
-
-// Add custom middleware
-context.registerMiddleware({
-  type: MiddlewareType.Context,
-  stage: MiddlewareStage.Loading,
-  apply: async (ctx) => {
-    console.log('Custom middleware executed')
-    // Custom logic here
-  }
-})
-```
-
-### Configuration File Reading
-
-```typescript
-// config.json
-{
-  "service": "file-config-service",
-  "port": 8080,
-  "dbs": [
-    {
-      "service": "mongo",
-      "host": "mongodb://localhost:27017",
-      "schema": "production"
-    }
-  ]
-}
-```
-
-```typescript
-import { makeServerContext } from '@owlmeans/server-context'
-
-// File configuration is automatically read via middleware
-const context = makeServerContext({} as any)
-
-// Configuration will be populated from files
-await context.init()
-
-// Access configuration
-const config = context.cfg
-console.log(`Service running on port ${config.port}`)
-```
-
-### Resource Management
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-const context = makeServerContext(config('resource-service'))
-
-// Access configuration resources
-const configResource = context.getConfigResource()
-const trustedResource = context.getConfigResource('trusted')
-const pluginResource = context.getConfigResource('plugin')
-
-// Create new configuration records
-await configResource.create({
-  id: 'feature-flag',
-  recordType: 'feature',
-  enabled: true,
-  description: 'Enable new feature'
-})
-
-// Query trusted entities
-const trustedEntities = await trustedResource.list({
-  criteria: { scopes: ['admin'] }
-})
-```
-
-### Plugin System Integration
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-const serverConfig = config('plugin-host', {
-  plugins: [
-    {
-      id: 'auth-plugin',
-      recordType: 'plugin',
-      name: 'Authentication Plugin',
-      version: '1.0.0',
-      enabled: true,
-      config: {
-        provider: 'oauth2',
-        clientId: 'app-client-id'
-      }
-    }
-  ]
-})
-
-const context = makeServerContext(serverConfig)
-
-// Access plugin configuration
-const pluginResource = context.getConfigResource('plugin')
-const authPlugin = await pluginResource.get('auth-plugin')
-
-if (authPlugin.enabled) {
-  // Initialize plugin
-  console.log(`Loading ${authPlugin.name} v${authPlugin.version}`)
-}
-```
-
-### Multi-Service Architecture
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-// Gateway service configuration
-const gatewayConfig = config('api-gateway', {
-  services: {
-    'user-service': {
-      protocol: 'http',
-      host: 'user-service',
-      port: 3001
-    },
-    'order-service': {
-      protocol: 'http', 
-      host: 'order-service',
-      port: 3002
-    },
-    'payment-service': {
-      protocol: 'https',
-      host: 'payment-service.external',
-      port: 443
-    }
-  },
-  
-  trusted: [
-    {
-      id: 'user-service',
-      recordType: 'trusted-source',
-      name: 'User Service',
-      scopes: ['users:*']
-    },
-    {
-      id: 'order-service', 
-      recordType: 'trusted-source',
-      name: 'Order Service',
-      scopes: ['orders:*', 'users:read']
-    }
-  ]
-})
-
-const gateway = makeServerContext(gatewayConfig)
-
-// Service can now route to other services with authentication
-```
-
-### Error Handling
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-try {
-  const context = makeServerContext(config('error-service'))
-  await context.init()
-} catch (error) {
-  console.error('Failed to initialize server context:', error)
-  
-  // Handle specific initialization errors
-  if (error.message.includes('database')) {
-    console.error('Database connection failed')
-  } else if (error.message.includes('config')) {
-    console.error('Configuration error')
-  }
-  
-  process.exit(1)
-}
+bun add @owlmeans/server-context
 ```
 
-## Advanced Features
+## Usage
 
-### Custom Context Extensions
+Usually called indirectly through `@owlmeans/server-app`:
 
 ```typescript
-import { makeServerContext, ServerContext, ServerConfig } from '@owlmeans/server-context'
-
-interface CustomConfig extends ServerConfig {
-  customFeature: boolean
-  apiKeys: string[]
-}
-
-interface CustomContext extends ServerContext<CustomConfig> {
-  customMethod: () => void
-}
-
-const createCustomContext = (cfg: CustomConfig): CustomContext => {
-  const context = makeServerContext(cfg) as CustomContext
-  
-  context.customMethod = () => {
-    console.log('Custom context method')
-  }
-  
-  return context
-}
+import { makeContext } from '@owlmeans/server-app'
+const context = makeContext(appConfig)
 ```
 
-### Dynamic Service Discovery
+When building a custom server context:
 
 ```typescript
 import { makeServerContext, config } from '@owlmeans/server-context'
 
-const context = makeServerContext(config('discovery-service'))
-
-// Dynamic service registration
-const discoverServices = async () => {
-  const services = await fetchAvailableServices()
-  
-  services.forEach(service => {
-    context.cfg.services[service.name] = {
-      protocol: service.protocol,
-      host: service.host,
-      port: service.port
-    }
-  })
-}
-
-await discoverServices()
+const serverContext = makeServerContext(
+  config(AppType.Backend, 'my-service', { port: 3000 })
+)
 ```
 
-### Health Checks
-
-```typescript
-import { makeServerContext, config } from '@owlmeans/server-context'
-
-const context = makeServerContext(config('health-service'))
-
-const healthCheck = async () => {
-  try {
-    // Check all registered services
-    const services = Object.keys(context.cfg.services)
-    const healthStatuses = await Promise.all(
-      services.map(async service => {
-        try {
-          await context.service(service)
-          return { service, status: 'healthy' }
-        } catch (error) {
-          return { service, status: 'unhealthy', error: error.message }
-        }
-      })
-    )
-    
-    return healthStatuses
-  } catch (error) {
-    return { status: 'error', message: error.message }
-  }
-}
-```
-
-## Integration with OwlMeans Ecosystem
-
-The `@owlmeans/server-context` package integrates with:
+## API
 
-- **@owlmeans/context**: Base context and dependency injection system
-- **@owlmeans/config**: Configuration management and resource handling
-- **@owlmeans/server-config**: Server-specific configuration structures
-- **@owlmeans/client-config**: Client configuration for fullstack apps
-- **@owlmeans/server-route**: Service routing and discovery
-- **@owlmeans/auth-common**: Authentication middleware and guards
-- **@owlmeans/mongo**: Database service integration
-- **@owlmeans/redis**: Cache service integration
+### `makeServerContext<C, T>(cfg): T`
 
-## Security Features
+Creates a server context with:
+- File-based config reader middleware (reads `CONFIG_DIR` / `config.json`)
+- `PLUGINS` config resource
+- Trusted key management resource
+- Ed25519 guard service registration
 
-### Built-in Authentication
-- Ed25519 signature-based authentication guard
-- Automatic authentication middleware
-- Trusted entity management
-- Secure service-to-service communication
+### `config<C>(type, service, cfg?): C`
 
-### Configuration Security
-- Secure file configuration reading
-- Environment variable support
-- Secret management integration
-- Access control for configuration resources
+Creates a `ServerConfig`. Alias re-exported from `@owlmeans/server-app`.
 
-## Best Practices
+### `ServerConfig`
 
-### Configuration Management
-- Use environment-specific configuration files
-- Store secrets in secure environment variables
-- Implement configuration validation
-- Use typed configuration interfaces
+Extends `CommonConfig` with `port?: number`, `security?: ServerSecurityConfig`.
 
-### Service Architecture
-- Register services during context initialization
-- Implement proper service lifecycle management
-- Use dependency injection for service access
-- Handle service failures gracefully
+### `ServerContext<C>`
 
-### Security
-- Always use authentication guards for protected services
-- Implement proper authorization checks
-- Validate all incoming requests
-- Use secure communication protocols
+Extends `BasicContext<C>` with `getApiServer(): ApiServer`.
 
-### Performance
-- Initialize context once during application startup
-- Cache frequently accessed configuration
-- Use lazy service initialization where appropriate
-- Monitor resource usage and optimize accordingly
+## Related Packages
 
-Fixes #32.
+- [`@owlmeans/context`](../context) — `BasicContext` base
+- [`@owlmeans/server-app`](../server-app) — higher-level `makeContext` that calls this internally
+- [`@owlmeans/server-config`](../server-config) — `sservice()` used to configure services

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-context",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -28,16 +28,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/client-config": "^0.1.2",
-    "@owlmeans/config": "^0.1.2",
-    "@owlmeans/context": "^0.1.2",
-    "@owlmeans/route": "^0.1.2",
-    "@owlmeans/server-config": "^0.1.2"
+    "@owlmeans/client-config": "^0.1.4",
+    "@owlmeans/config": "^0.1.4",
+    "@owlmeans/context": "^0.1.4",
+    "@owlmeans/route": "^0.1.4",
+    "@owlmeans/server-config": "^0.1.4"
   },
   "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
     "@types/node": "^24.10.1",
     "nodemon": "^3.1.11",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.2"
   },
   "publishConfig": {
     "access": "public"

package/tsconfig.json

@@ -1,14 +1,15 @@
 {
   "extends": [
-    "../tsconfig.default.json",
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
   ],
   "compilerOptions": {
-    "rootDir": "./src/", /* Specify the root folder within your source files. */
-    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+    "rootDir": "./src/",
+    "outDir": "./build/"
   },
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
     "./*.ts"
   ]
-}
+}