BREAKING CHANGE(service): expand service lifecycle management with instance-aware hooks, startup timeouts, labels, readiness waits, and auto-restart support
This commit is contained in:
@@ -1,5 +1,12 @@
|
||||
# Changelog
|
||||
|
||||
## 2026-03-20 - 8.0.0 - BREAKING CHANGE(service)
|
||||
expand service lifecycle management with instance-aware hooks, startup timeouts, labels, readiness waits, and auto-restart support
|
||||
|
||||
- Change service stop and health check callbacks to receive the started instance and expose it via service.instance
|
||||
- Add per-service and global startup timeout handling plus waitForState, waitForRunning, and waitForStopped readiness helpers
|
||||
- Support service labels, label-based manager queries, and auto-restart lifecycle events with configurable backoff
|
||||
|
||||
## 2026-02-15 - 6.1.2 - fix(deps)
|
||||
bump @push.rocks/smarttime to ^4.2.3
|
||||
|
||||
|
||||
16
package.json
16
package.json
@@ -7,7 +7,7 @@
|
||||
"typings": "dist_ts/index.d.ts",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"test": "(tstest test/ --verbose --logfile --timeout 120)",
|
||||
"test": "(tstest test/ --verbose --logfile --timeout 300)",
|
||||
"build": "(tsbuild tsfolders)",
|
||||
"buildDocs": "tsdoc"
|
||||
},
|
||||
@@ -34,21 +34,21 @@
|
||||
},
|
||||
"homepage": "https://code.foss.global/push.rocks/taskbuffer#readme",
|
||||
"dependencies": {
|
||||
"@design.estate/dees-element": "^2.1.6",
|
||||
"@push.rocks/lik": "^6.2.2",
|
||||
"@design.estate/dees-element": "^2.2.3",
|
||||
"@push.rocks/lik": "^6.3.1",
|
||||
"@push.rocks/smartdelay": "^3.0.5",
|
||||
"@push.rocks/smartlog": "^3.1.11",
|
||||
"@push.rocks/smartlog": "^3.2.1",
|
||||
"@push.rocks/smartpromise": "^4.2.3",
|
||||
"@push.rocks/smartrx": "^3.0.10",
|
||||
"@push.rocks/smarttime": "^4.2.3",
|
||||
"@push.rocks/smartunique": "^3.0.9"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@git.zone/tsbuild": "^4.1.2",
|
||||
"@git.zone/tsbundle": "^2.8.3",
|
||||
"@git.zone/tsbuild": "^4.3.0",
|
||||
"@git.zone/tsbundle": "^2.9.1",
|
||||
"@git.zone/tsrun": "^2.0.1",
|
||||
"@git.zone/tstest": "^3.1.8",
|
||||
"@types/node": "^25.2.3"
|
||||
"@git.zone/tstest": "^3.5.0",
|
||||
"@types/node": "^25.5.0"
|
||||
},
|
||||
"files": [
|
||||
"ts/**/*",
|
||||
|
||||
5094
pnpm-lock.yaml
generated
5094
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
@@ -94,17 +94,45 @@
|
||||
accessor count = 0;
|
||||
```
|
||||
|
||||
## Dependencies (as of v4.2.0)
|
||||
- `@design.estate/dees-element` ^2.1.6 - TC39 decorators with `accessor` keyword
|
||||
- `@push.rocks/lik` ^6.2.2 - Data structures
|
||||
## Service Lifecycle System (v7.0.0+)
|
||||
|
||||
### Service<T>
|
||||
- `new Service<T>(name)` or `new Service<T>(options: IServiceOptions<T>)`
|
||||
- Builder pattern: `.critical()`, `.optional()`, `.dependsOn(...)`, `.withStart(fn)`, `.withStop(fn)`, `.withHealthCheck(fn, config?)`, `.withRetry(config)`, `.withStartupTimeout(ms)`, `.withLabels(labels)`
|
||||
- Subclass pattern: override `serviceStart()`, `serviceStop()`, `serviceHealthCheck()`
|
||||
- State machine: `stopped` → `starting` → `running` → `degraded` → `failed` → `stopping`
|
||||
- `service.instance` — stores the value returned from `start()` (e.g. a database pool)
|
||||
- `withStop(fn)` and `withHealthCheck(fn)` receive the instance as argument: `(instance: T) => Promise<void>`
|
||||
- `waitForState(target, timeoutMs?)`, `waitForRunning(timeoutMs?)`, `waitForStopped(timeoutMs?)` — programmatic readiness gates
|
||||
- Per-service startup timeout via `withStartupTimeout(ms)` or `startupTimeoutMs` in options
|
||||
- Labels: `setLabel`, `getLabel`, `removeLabel`, `hasLabel`, `withLabels`
|
||||
- Health checks: configurable via `IHealthCheckConfig` with `intervalMs`, `timeoutMs`, `failuresBeforeDegraded`, `failuresBeforeFailed`
|
||||
- Auto-restart on health failure: `autoRestart: true` in `IHealthCheckConfig` with `maxAutoRestarts`, `autoRestartDelayMs`, `autoRestartBackoffFactor`
|
||||
- Events via `eventSubject`: `'started'`, `'stopped'`, `'failed'`, `'degraded'`, `'recovered'`, `'retrying'`, `'healthCheck'`, `'autoRestarting'`
|
||||
|
||||
### ServiceManager
|
||||
- `manager.addService(service)` / `manager.addServiceFromOptions(options)` / `manager.removeService(name)`
|
||||
- Dependency-ordered startup via topological sort (Kahn's algorithm), level-by-level parallel
|
||||
- Critical service failure aborts startup with rollback; optional service failure continues
|
||||
- Retry with exponential backoff + jitter
|
||||
- Reverse-dependency-ordered shutdown with per-service timeout
|
||||
- `restartService(name)` — cascade stops dependents, restarts target, restarts dependents
|
||||
- `getHealth()` — aggregated `'healthy' | 'degraded' | 'unhealthy'` status
|
||||
- `getServicesByLabel(key, value)` / `getServicesStatusByLabel(key, value)` — label-based queries
|
||||
- Circular dependency detection
|
||||
- Global startup timeout enforcement via `startupTimeoutMs` in `IServiceManagerOptions`
|
||||
|
||||
## Dependencies (as of v7.0.0)
|
||||
- `@design.estate/dees-element` ^2.2.3 - TC39 decorators with `accessor` keyword
|
||||
- `@push.rocks/lik` ^6.3.1 - Data structures
|
||||
- `@push.rocks/smartdelay` ^3.0.5 - Delay utilities
|
||||
- `@push.rocks/smartlog` ^3.1.11 - Logging
|
||||
- `@push.rocks/smartlog` ^3.2.1 - Logging
|
||||
- `@push.rocks/smartpromise` ^4.2.3 - Promise utilities
|
||||
- `@push.rocks/smartrx` ^3.0.10 - RxJS wrapper
|
||||
- `@push.rocks/smarttime` ^4.1.1 - Time/cron utilities
|
||||
- `@push.rocks/smarttime` ^4.2.3 - Time/cron utilities
|
||||
- `@push.rocks/smartunique` ^3.0.9 - Unique ID generation
|
||||
- `@git.zone/tsbuild` ^4.1.2 - Build tool
|
||||
- `@git.zone/tsbundle` ^2.8.3 - Bundler (for browser tests)
|
||||
- `@git.zone/tsbuild` ^4.3.0 - Build tool
|
||||
- `@git.zone/tsbundle` ^2.9.1 - Bundler (for browser tests)
|
||||
- `@git.zone/tsrun` ^2.0.1 - TypeScript runner
|
||||
- `@git.zone/tstest` ^3.1.8 - Test runner (supports `.chromium.ts` files)
|
||||
- `@types/node` ^25.2.3 - Node.js type definitions
|
||||
- `@git.zone/tstest` ^3.5.0 - Test runner (supports `.chromium.ts` files)
|
||||
- `@types/node` ^25.5.0 - Node.js type definitions
|
||||
|
||||
269
readme.md
269
readme.md
@@ -1,6 +1,6 @@
|
||||
# @push.rocks/taskbuffer 🚀
|
||||
|
||||
> **Modern TypeScript task orchestration with constraint-based concurrency, smart buffering, scheduling, labels, and real-time event streaming**
|
||||
> **Modern TypeScript task orchestration and service lifecycle management with constraint-based concurrency, smart buffering, scheduling, health checks, and real-time event streaming**
|
||||
|
||||
[](https://www.npmjs.com/package/@push.rocks/taskbuffer)
|
||||
[](https://www.typescriptlang.org/)
|
||||
@@ -21,6 +21,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
|
||||
- **🏷️ Labels** — Attach arbitrary `Record<string, string>` metadata (userId, tenantId, etc.) for multi-tenant filtering
|
||||
- **📡 Push-Based Events** — rxjs `Subject<ITaskEvent>` on every Task and TaskManager for real-time state change notifications
|
||||
- **🛡️ Error Handling** — Configurable error propagation with `catchErrors`, error tracking, and clear error state
|
||||
- **🩺 Service Lifecycle Management** — `Service` and `ServiceManager` for long-running components (databases, servers, queues) with health checks, auto-restart, dependency ordering, and instance access
|
||||
- **🎨 Web Component Dashboard** — Built-in Lit-based dashboard for real-time task visualization
|
||||
- **🌐 Distributed Coordination** — Abstract coordinator for multi-instance task deduplication
|
||||
|
||||
@@ -788,6 +789,196 @@ manager.descheduleTaskByName('Deploy'); // Remove cron schedule only
|
||||
manager.removeConstraintGroup('domain-mutex'); // By name
|
||||
```
|
||||
|
||||
## 🩺 Service Lifecycle Management
|
||||
|
||||
For long-running components like database connections, HTTP servers, and message queues, taskbuffer provides `Service` and `ServiceManager` — a complete lifecycle management system with health checks, dependency ordering, retry, auto-restart, and typed instance access.
|
||||
|
||||
### Basic Service — Builder Pattern
|
||||
|
||||
```typescript
|
||||
import { Service, ServiceManager } from '@push.rocks/taskbuffer';
|
||||
|
||||
const dbService = new Service<DatabasePool>('Database')
|
||||
.critical()
|
||||
.withStart(async () => {
|
||||
const pool = new DatabasePool({ host: 'localhost', port: 5432 });
|
||||
await pool.connect();
|
||||
return pool; // stored as service.instance
|
||||
})
|
||||
.withStop(async (pool) => {
|
||||
await pool.disconnect(); // receives the instance from start
|
||||
})
|
||||
.withHealthCheck(async (pool) => {
|
||||
return await pool.ping(); // receives the instance too
|
||||
});
|
||||
|
||||
await dbService.start();
|
||||
dbService.instance!.query('SELECT 1'); // typed access to the pool
|
||||
await dbService.stop();
|
||||
```
|
||||
|
||||
The `start()` return value is stored as `service.instance` and automatically passed to `stop()` and `healthCheck()` functions — no need for external closures or shared variables.
|
||||
|
||||
### Service with Dependencies & Health Checks
|
||||
|
||||
```typescript
|
||||
const cacheService = new Service('Redis')
|
||||
.optional()
|
||||
.withStart(async () => new RedisClient())
|
||||
.withStop(async (client) => client.quit())
|
||||
.withHealthCheck(async (client) => client.isReady, {
|
||||
intervalMs: 10000, // check every 10s
|
||||
timeoutMs: 3000, // 3s timeout per check
|
||||
failuresBeforeDegraded: 3, // 3 consecutive failures → 'degraded'
|
||||
failuresBeforeFailed: 5, // 5 consecutive failures → 'failed'
|
||||
autoRestart: true, // auto-restart when failed
|
||||
maxAutoRestarts: 5, // give up after 5 restart attempts
|
||||
autoRestartDelayMs: 2000, // start with 2s delay
|
||||
autoRestartBackoffFactor: 2, // double delay each attempt
|
||||
});
|
||||
|
||||
const apiService = new Service('API')
|
||||
.critical()
|
||||
.dependsOn('Database', 'Redis')
|
||||
.withStart(async () => {
|
||||
const server = createServer();
|
||||
await server.listen(3000);
|
||||
return server;
|
||||
})
|
||||
.withStop(async (server) => server.close())
|
||||
.withStartupTimeout(10000); // fail if start takes > 10s
|
||||
```
|
||||
|
||||
### ServiceManager — Orchestration
|
||||
|
||||
`ServiceManager` handles dependency-ordered startup, failure isolation, and aggregated health reporting:
|
||||
|
||||
```typescript
|
||||
const manager = new ServiceManager({
|
||||
name: 'MyApp',
|
||||
startupTimeoutMs: 60000, // global startup timeout
|
||||
shutdownTimeoutMs: 15000, // per-service shutdown timeout
|
||||
defaultRetry: { maxRetries: 3, baseDelayMs: 1000, backoffFactor: 2 },
|
||||
});
|
||||
|
||||
manager.addService(dbService);
|
||||
manager.addService(cacheService);
|
||||
manager.addService(apiService);
|
||||
|
||||
await manager.start();
|
||||
// ✅ Starts Database first, then Redis (parallel with DB since independent),
|
||||
// then API (after both deps are running)
|
||||
// ❌ If Database (critical) fails → rollback, stop everything, throw
|
||||
// ⚠️ If Redis (optional) fails → log warning, continue, health = 'degraded'
|
||||
|
||||
// Health aggregation
|
||||
const health = manager.getHealth();
|
||||
// { overall: 'healthy', services: [...], startedAt: 1706284800000, uptime: 42000 }
|
||||
|
||||
// Cascade restart — stops dependents first, restarts target, then restarts dependents
|
||||
await manager.restartService('Database');
|
||||
|
||||
// Graceful reverse-order shutdown
|
||||
await manager.stop();
|
||||
```
|
||||
|
||||
### Subclass Pattern
|
||||
|
||||
For complex services, extend `Service` and override the lifecycle hooks:
|
||||
|
||||
```typescript
|
||||
class PostgresService extends Service<Pool> {
|
||||
constructor(private config: PoolConfig) {
|
||||
super('Postgres');
|
||||
this.critical();
|
||||
}
|
||||
|
||||
protected async serviceStart(): Promise<Pool> {
|
||||
const pool = new Pool(this.config);
|
||||
await pool.connect();
|
||||
return pool;
|
||||
}
|
||||
|
||||
protected async serviceStop(): Promise<void> {
|
||||
await this.instance?.end();
|
||||
}
|
||||
|
||||
protected async serviceHealthCheck(): Promise<boolean> {
|
||||
const result = await this.instance?.query('SELECT 1');
|
||||
return result?.rows.length === 1;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Waiting for Service Readiness
|
||||
|
||||
Programmatically wait for a service to reach a specific state:
|
||||
|
||||
```typescript
|
||||
// Wait for the service to be running (with timeout)
|
||||
await dbService.waitForRunning(10000);
|
||||
|
||||
// Wait for any state
|
||||
await service.waitForState(['running', 'degraded'], 5000);
|
||||
|
||||
// Wait for shutdown
|
||||
await service.waitForStopped();
|
||||
```
|
||||
|
||||
### Service Labels
|
||||
|
||||
Tag services with metadata for filtering and grouping:
|
||||
|
||||
```typescript
|
||||
const service = new Service('Redis')
|
||||
.withLabels({ type: 'cache', env: 'production', region: 'eu-west' })
|
||||
.withStart(async () => new RedisClient())
|
||||
.withStop(async (client) => client.quit());
|
||||
|
||||
// Query by label in ServiceManager
|
||||
const caches = manager.getServicesByLabel('type', 'cache');
|
||||
const prodStatuses = manager.getServicesStatusByLabel('env', 'production');
|
||||
```
|
||||
|
||||
### Service Events
|
||||
|
||||
Every `Service` emits events via an rxjs `Subject<IServiceEvent>`:
|
||||
|
||||
```typescript
|
||||
service.eventSubject.subscribe((event) => {
|
||||
console.log(`[${event.type}] ${event.serviceName} → ${event.state}`);
|
||||
});
|
||||
// [started] Database → running
|
||||
// [healthCheck] Database → running
|
||||
// [degraded] Database → degraded
|
||||
// [autoRestarting] Database → failed
|
||||
// [started] Database → running
|
||||
// [recovered] Database → running
|
||||
// [stopped] Database → stopped
|
||||
```
|
||||
|
||||
| Event Type | When |
|
||||
| --- | --- |
|
||||
| `'started'` | Service started successfully |
|
||||
| `'stopped'` | Service stopped |
|
||||
| `'failed'` | Service start failed or health check threshold exceeded |
|
||||
| `'degraded'` | Health check failures exceeded `failuresBeforeDegraded` |
|
||||
| `'recovered'` | Health check succeeded while in degraded state |
|
||||
| `'retrying'` | ServiceManager retrying a failed start attempt |
|
||||
| `'healthCheck'` | Health check completed (success or failure) |
|
||||
| `'autoRestarting'` | Auto-restart scheduled after health check failure |
|
||||
|
||||
`ServiceManager.serviceSubject` aggregates events from all registered services.
|
||||
|
||||
### Service State Machine
|
||||
|
||||
```
|
||||
stopped → starting → running → degraded → failed
|
||||
↑ ↓ ↓ ↓
|
||||
└── stopping ←───────────────────┴─────────┘
|
||||
(auto-restart)
|
||||
```
|
||||
|
||||
## 🎨 Web Component Dashboard
|
||||
|
||||
Visualize your tasks in real-time with the included Lit-based web component:
|
||||
@@ -970,6 +1161,8 @@ const acmeTasks = manager.getTasksMetadataByLabel('tenantId', 'acme');
|
||||
| `TaskOnce` | Single-execution guard |
|
||||
| `TaskDebounced` | Debounced task using rxjs |
|
||||
| `TaskStep` | Step tracking unit (internal, exposed via metadata) |
|
||||
| `Service<T>` | Long-running component with start/stop lifecycle, health checks, auto-restart, and typed instance access |
|
||||
| `ServiceManager` | Service orchestrator with dependency ordering, failure isolation, retry, and health aggregation |
|
||||
|
||||
### Task Constructor Options
|
||||
|
||||
@@ -1080,10 +1273,72 @@ const acmeTasks = manager.getTasksMetadataByLabel('tenantId', 'acme');
|
||||
| `taskMap` | `ObjectMap<Task>` | Internal task registry |
|
||||
| `constraintGroups` | `TaskConstraintGroup[]` | Registered constraint groups |
|
||||
|
||||
### Service Builder Methods
|
||||
|
||||
| Method | Returns | Description |
|
||||
| --- | --- | --- |
|
||||
| `critical()` | `this` | Mark as critical (startup failure aborts ServiceManager) |
|
||||
| `optional()` | `this` | Mark as optional (startup failure is tolerated) |
|
||||
| `dependsOn(...names)` | `this` | Declare dependencies by service name |
|
||||
| `withStart(fn)` | `this` | Set start function: `() => Promise<T>` |
|
||||
| `withStop(fn)` | `this` | Set stop function: `(instance: T) => Promise<void>` |
|
||||
| `withHealthCheck(fn, config?)` | `this` | Set health check: `(instance: T) => Promise<boolean>` |
|
||||
| `withRetry(config)` | `this` | Set retry config: `{ maxRetries, baseDelayMs, maxDelayMs, backoffFactor }` |
|
||||
| `withStartupTimeout(ms)` | `this` | Per-service startup timeout |
|
||||
| `withLabels(labels)` | `this` | Attach key-value labels |
|
||||
|
||||
### Service Methods
|
||||
|
||||
| Method | Returns | Description |
|
||||
| --- | --- | --- |
|
||||
| `start()` | `Promise<T>` | Start the service (no-op if already running) |
|
||||
| `stop()` | `Promise<void>` | Stop the service (no-op if already stopped) |
|
||||
| `checkHealth()` | `Promise<boolean \| undefined>` | Run health check manually |
|
||||
| `waitForState(target, timeoutMs?)` | `Promise<void>` | Wait for service to reach a state |
|
||||
| `waitForRunning(timeoutMs?)` | `Promise<void>` | Wait for `'running'` state |
|
||||
| `waitForStopped(timeoutMs?)` | `Promise<void>` | Wait for `'stopped'` state |
|
||||
| `getStatus()` | `IServiceStatus` | Full status snapshot |
|
||||
| `setLabel(key, value)` | `void` | Set a label |
|
||||
| `getLabel(key)` | `string \| undefined` | Get a label value |
|
||||
| `removeLabel(key)` | `boolean` | Remove a label |
|
||||
| `hasLabel(key, value?)` | `boolean` | Check label existence / value |
|
||||
|
||||
### Service Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `name` | `string` | Service identifier |
|
||||
| `state` | `TServiceState` | Current state (`stopped`, `starting`, `running`, `degraded`, `failed`, `stopping`) |
|
||||
| `instance` | `T \| undefined` | The value returned from `start()` |
|
||||
| `criticality` | `TServiceCriticality` | `'critical'` or `'optional'` |
|
||||
| `dependencies` | `string[]` | Dependency names |
|
||||
| `labels` | `Record<string, string>` | Attached labels |
|
||||
| `eventSubject` | `Subject<IServiceEvent>` | rxjs Subject emitting lifecycle events |
|
||||
| `errorCount` | `number` | Total error count |
|
||||
| `retryCount` | `number` | Retry attempts during last startup |
|
||||
|
||||
### ServiceManager Methods
|
||||
|
||||
| Method | Returns | Description |
|
||||
| --- | --- | --- |
|
||||
| `addService(service)` | `void` | Register a service |
|
||||
| `addServiceFromOptions(options)` | `Service<T>` | Create and register from options |
|
||||
| `removeService(name)` | `void` | Remove service (throws if others depend on it) |
|
||||
| `start()` | `Promise<void>` | Start all services in dependency order |
|
||||
| `stop()` | `Promise<void>` | Stop all services in reverse order |
|
||||
| `restartService(name)` | `Promise<void>` | Cascade restart with dependents |
|
||||
| `getService(name)` | `Service \| undefined` | Look up by name |
|
||||
| `getServiceStatus(name)` | `IServiceStatus \| undefined` | Single service status |
|
||||
| `getAllStatuses()` | `IServiceStatus[]` | All service statuses |
|
||||
| `getHealth()` | `IServiceManagerHealth` | Aggregated health report |
|
||||
| `getServicesByLabel(key, value)` | `Service[]` | Filter services by label |
|
||||
| `getServicesStatusByLabel(key, value)` | `IServiceStatus[]` | Filter statuses by label |
|
||||
|
||||
### Exported Types
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
// Task types
|
||||
ITaskMetadata,
|
||||
ITaskExecutionReport,
|
||||
ITaskExecution,
|
||||
@@ -1096,6 +1351,18 @@ import type {
|
||||
IRateLimitConfig,
|
||||
TResultSharingMode,
|
||||
StepNames,
|
||||
// Service types
|
||||
IServiceOptions,
|
||||
IServiceStatus,
|
||||
IServiceEvent,
|
||||
IServiceManagerOptions,
|
||||
IServiceManagerHealth,
|
||||
IRetryConfig,
|
||||
IHealthCheckConfig,
|
||||
TServiceState,
|
||||
TServiceCriticality,
|
||||
TServiceEventType,
|
||||
TOverallHealth,
|
||||
} from '@push.rocks/taskbuffer';
|
||||
```
|
||||
|
||||
|
||||
@@ -514,4 +514,381 @@ tap.test('should support addServiceFromOptions', async () => {
|
||||
await manager.stop();
|
||||
});
|
||||
|
||||
// ═══════════════════════════════════════════════════════════
|
||||
// NEW TESTS: Improvements 1-5
|
||||
// ═══════════════════════════════════════════════════════════
|
||||
|
||||
// ── Test 19: service.instance stores start result ──────────
|
||||
|
||||
tap.test('should store start result as service.instance', async () => {
|
||||
const pool = { query: (sql: string) => `result: ${sql}` };
|
||||
|
||||
const service = new taskbuffer.Service<typeof pool>('DB')
|
||||
.withStart(async () => pool)
|
||||
.withStop(async (inst) => {});
|
||||
|
||||
expect(service.instance).toBeUndefined();
|
||||
|
||||
const result = await service.start();
|
||||
expect(result).toEqual(pool);
|
||||
expect(service.instance).toEqual(pool);
|
||||
expect(service.instance!.query('SELECT 1')).toEqual('result: SELECT 1');
|
||||
|
||||
// Status should report hasInstance
|
||||
expect(service.getStatus().hasInstance).toBeTrue();
|
||||
|
||||
await service.stop();
|
||||
expect(service.instance).toBeUndefined();
|
||||
expect(service.getStatus().hasInstance).toBeFalse();
|
||||
});
|
||||
|
||||
// ── Test 20: stop receives the instance ────────────────────
|
||||
|
||||
tap.test('should pass instance to stop function', async () => {
|
||||
let receivedInstance: any = null;
|
||||
|
||||
const service = new taskbuffer.Service<{ id: number }>('InstanceStop')
|
||||
.withStart(async () => ({ id: 42 }))
|
||||
.withStop(async (inst) => { receivedInstance = inst; });
|
||||
|
||||
await service.start();
|
||||
await service.stop();
|
||||
|
||||
expect(receivedInstance).toBeTruthy();
|
||||
expect(receivedInstance.id).toEqual(42);
|
||||
});
|
||||
|
||||
// ── Test 21: healthCheck receives the instance ─────────────
|
||||
|
||||
tap.test('should pass instance to health check function', async () => {
|
||||
let checkedInstance: any = null;
|
||||
|
||||
const service = new taskbuffer.Service<{ healthy: boolean }>('InstanceHealth')
|
||||
.withStart(async () => ({ healthy: true }))
|
||||
.withStop(async () => {})
|
||||
.withHealthCheck(async (inst) => {
|
||||
checkedInstance = inst;
|
||||
return inst.healthy;
|
||||
}, { intervalMs: 60000 }); // long interval so it doesn't auto-run
|
||||
|
||||
await service.start();
|
||||
|
||||
// Manually trigger health check
|
||||
const ok = await service.checkHealth();
|
||||
expect(ok).toBeTrue();
|
||||
expect(checkedInstance).toBeTruthy();
|
||||
expect(checkedInstance.healthy).toBeTrue();
|
||||
|
||||
await service.stop();
|
||||
});
|
||||
|
||||
// ── Test 22: double start returns existing instance ────────
|
||||
|
||||
tap.test('should return existing instance on double start', async () => {
|
||||
let callCount = 0;
|
||||
const service = new taskbuffer.Service<number>('DoubleInstance')
|
||||
.withStart(async () => { callCount++; return callCount; })
|
||||
.withStop(async () => {});
|
||||
|
||||
const first = await service.start();
|
||||
const second = await service.start();
|
||||
|
||||
expect(first).toEqual(1);
|
||||
expect(second).toEqual(1); // should return same instance, not call start again
|
||||
expect(callCount).toEqual(1);
|
||||
|
||||
await service.stop();
|
||||
});
|
||||
|
||||
// ── Test 23: Labels on Service ─────────────────────────────
|
||||
|
||||
tap.test('should support labels on services', async () => {
|
||||
const service = new taskbuffer.Service('LabeledService')
|
||||
.withLabels({ type: 'database', env: 'production' })
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {});
|
||||
|
||||
expect(service.hasLabel('type')).toBeTrue();
|
||||
expect(service.hasLabel('type', 'database')).toBeTrue();
|
||||
expect(service.hasLabel('type', 'cache')).toBeFalse();
|
||||
expect(service.getLabel('env')).toEqual('production');
|
||||
|
||||
service.setLabel('region', 'eu-west');
|
||||
expect(service.hasLabel('region')).toBeTrue();
|
||||
|
||||
service.removeLabel('env');
|
||||
expect(service.hasLabel('env')).toBeFalse();
|
||||
|
||||
// Labels in status
|
||||
const status = service.getStatus();
|
||||
expect(status.labels).toBeTruthy();
|
||||
expect(status.labels!.type).toEqual('database');
|
||||
expect(status.labels!.region).toEqual('eu-west');
|
||||
});
|
||||
|
||||
// ── Test 24: Labels via IServiceOptions ────────────────────
|
||||
|
||||
tap.test('should accept labels in options constructor', async () => {
|
||||
const service = new taskbuffer.Service({
|
||||
name: 'OptionsLabeled',
|
||||
start: async () => {},
|
||||
stop: async () => {},
|
||||
labels: { kind: 'cache' },
|
||||
});
|
||||
|
||||
expect(service.hasLabel('kind', 'cache')).toBeTrue();
|
||||
});
|
||||
|
||||
// ── Test 25: ServiceManager.getServicesByLabel ─────────────
|
||||
|
||||
tap.test('should query services by label in ServiceManager', async () => {
|
||||
const manager = new taskbuffer.ServiceManager({ name: 'LabelQueryTest' });
|
||||
|
||||
manager.addService(
|
||||
new taskbuffer.Service('Redis')
|
||||
.withLabels({ type: 'cache', tier: 'fast' })
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {}),
|
||||
);
|
||||
|
||||
manager.addService(
|
||||
new taskbuffer.Service('Memcached')
|
||||
.withLabels({ type: 'cache', tier: 'fast' })
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {}),
|
||||
);
|
||||
|
||||
manager.addService(
|
||||
new taskbuffer.Service('Postgres')
|
||||
.withLabels({ type: 'database', tier: 'slow' })
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {}),
|
||||
);
|
||||
|
||||
const caches = manager.getServicesByLabel('type', 'cache');
|
||||
expect(caches.length).toEqual(2);
|
||||
|
||||
const databases = manager.getServicesByLabel('type', 'database');
|
||||
expect(databases.length).toEqual(1);
|
||||
expect(databases[0].name).toEqual('Postgres');
|
||||
|
||||
const statuses = manager.getServicesStatusByLabel('tier', 'fast');
|
||||
expect(statuses.length).toEqual(2);
|
||||
|
||||
await manager.stop();
|
||||
});
|
||||
|
||||
// ── Test 26: waitForState / waitForRunning ──────────────────
|
||||
|
||||
tap.test('should support waitForState and waitForRunning', async () => {
|
||||
const service = new taskbuffer.Service('WaitService')
|
||||
.withStart(async () => {
|
||||
await smartdelay.delayFor(50);
|
||||
})
|
||||
.withStop(async () => {});
|
||||
|
||||
// Start in background
|
||||
const startPromise = service.start();
|
||||
|
||||
// Wait for running state
|
||||
await service.waitForRunning(2000);
|
||||
expect(service.state).toEqual('running');
|
||||
|
||||
await startPromise;
|
||||
|
||||
// Now wait for stopped
|
||||
const stopPromise = service.stop();
|
||||
await service.waitForStopped(2000);
|
||||
expect(service.state).toEqual('stopped');
|
||||
|
||||
await stopPromise;
|
||||
});
|
||||
|
||||
// ── Test 27: waitForState timeout ──────────────────────────
|
||||
|
||||
tap.test('should timeout when waiting for a state that never comes', async () => {
|
||||
const service = new taskbuffer.Service('TimeoutWait')
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {});
|
||||
|
||||
// Service is stopped, wait for 'running' with a short timeout
|
||||
let caught = false;
|
||||
try {
|
||||
await service.waitForState('running', 100);
|
||||
} catch (err) {
|
||||
caught = true;
|
||||
expect((err as Error).message).toInclude('timed out');
|
||||
expect((err as Error).message).toInclude('running');
|
||||
}
|
||||
|
||||
expect(caught).toBeTrue();
|
||||
});
|
||||
|
||||
// ── Test 28: waitForState already in target state ──────────
|
||||
|
||||
tap.test('should resolve immediately if already in target state', async () => {
|
||||
const service = new taskbuffer.Service('AlreadyThere')
|
||||
.withStart(async () => {})
|
||||
.withStop(async () => {});
|
||||
|
||||
// Already stopped
|
||||
await service.waitForState('stopped', 100); // should not throw
|
||||
|
||||
await service.start();
|
||||
await service.waitForState('running', 100); // should not throw
|
||||
|
||||
await service.stop();
|
||||
});
|
||||
|
||||
// ── Test 29: Per-service startup timeout ───────────────────
|
||||
|
||||
tap.test('should timeout when serviceStart hangs', async () => {
|
||||
const service = new taskbuffer.Service('SlowStart')
|
||||
.withStart(async () => {
|
||||
await smartdelay.delayFor(5000); // very slow
|
||||
})
|
||||
.withStop(async () => {})
|
||||
.withStartupTimeout(100); // 100ms timeout
|
||||
|
||||
let caught = false;
|
||||
try {
|
||||
await service.start();
|
||||
} catch (err) {
|
||||
caught = true;
|
||||
expect((err as Error).message).toInclude('startup timed out');
|
||||
expect((err as Error).message).toInclude('100ms');
|
||||
}
|
||||
|
||||
expect(caught).toBeTrue();
|
||||
expect(service.state).toEqual('failed');
|
||||
});
|
||||
|
||||
// ── Test 30: Startup timeout via options ────────────────────
|
||||
|
||||
tap.test('should accept startupTimeoutMs in options constructor', async () => {
|
||||
const service = new taskbuffer.Service({
|
||||
name: 'TimeoutOptions',
|
||||
start: async () => { await smartdelay.delayFor(5000); },
|
||||
stop: async () => {},
|
||||
startupTimeoutMs: 100,
|
||||
});
|
||||
|
||||
let caught = false;
|
||||
try {
|
||||
await service.start();
|
||||
} catch (err) {
|
||||
caught = true;
|
||||
expect((err as Error).message).toInclude('startup timed out');
|
||||
}
|
||||
|
||||
expect(caught).toBeTrue();
|
||||
});
|
||||
|
||||
// ── Test 31: Auto-restart on health check failure ──────────
|
||||
|
||||
tap.test('should auto-restart when health checks fail', async () => {
|
||||
let startCount = 0;
|
||||
let healthy = false;
|
||||
|
||||
const service = new taskbuffer.Service('AutoRestart')
|
||||
.withStart(async () => {
|
||||
startCount++;
|
||||
// After first restart, become healthy
|
||||
if (startCount >= 2) {
|
||||
healthy = true;
|
||||
}
|
||||
})
|
||||
.withStop(async () => {})
|
||||
.withHealthCheck(async () => healthy, {
|
||||
intervalMs: 30000, // we'll call checkHealth manually
|
||||
failuresBeforeDegraded: 1,
|
||||
failuresBeforeFailed: 2,
|
||||
autoRestart: true,
|
||||
maxAutoRestarts: 3,
|
||||
autoRestartDelayMs: 50,
|
||||
autoRestartBackoffFactor: 1,
|
||||
});
|
||||
|
||||
await service.start();
|
||||
expect(startCount).toEqual(1);
|
||||
|
||||
// Fail health checks manually to push to failed
|
||||
await service.checkHealth(); // 1 failure -> degraded
|
||||
expect(service.state).toEqual('degraded');
|
||||
|
||||
await service.checkHealth(); // 2 failures -> failed + auto-restart scheduled
|
||||
expect(service.state).toEqual('failed');
|
||||
|
||||
// Wait for auto-restart to complete
|
||||
await service.waitForRunning(2000);
|
||||
expect(service.state).toEqual('running');
|
||||
expect(startCount).toEqual(2);
|
||||
|
||||
await service.stop();
|
||||
});
|
||||
|
||||
// ── Test 32: Auto-restart max attempts ─────────────────────
|
||||
|
||||
tap.test('should stop auto-restarting after max attempts', async () => {
|
||||
let startCount = 0;
|
||||
const events: string[] = [];
|
||||
|
||||
const service = new taskbuffer.Service('MaxRestart')
|
||||
.withStart(async () => {
|
||||
startCount++;
|
||||
if (startCount > 1) {
|
||||
throw new Error('always fails');
|
||||
}
|
||||
})
|
||||
.withStop(async () => {})
|
||||
.withHealthCheck(async () => false, {
|
||||
intervalMs: 60000,
|
||||
failuresBeforeDegraded: 1,
|
||||
failuresBeforeFailed: 2,
|
||||
autoRestart: true,
|
||||
maxAutoRestarts: 2,
|
||||
autoRestartDelayMs: 50,
|
||||
autoRestartBackoffFactor: 1,
|
||||
});
|
||||
|
||||
service.eventSubject.subscribe((e) => events.push(e.type));
|
||||
|
||||
await service.start();
|
||||
expect(startCount).toEqual(1);
|
||||
|
||||
// Push to failed
|
||||
await service.checkHealth();
|
||||
await service.checkHealth();
|
||||
|
||||
// Wait for auto-restart attempts to exhaust
|
||||
await smartdelay.delayFor(500);
|
||||
|
||||
// Should have emitted autoRestarting events
|
||||
expect(events).toContain('autoRestarting');
|
||||
|
||||
// Service should be in failed state (restarts exhausted)
|
||||
expect(service.state).toEqual('failed');
|
||||
|
||||
// Clean up
|
||||
await service.stop();
|
||||
});
|
||||
|
||||
// ── Test 33: Builder chaining with new methods ─────────────
|
||||
|
||||
tap.test('should chain all new builder methods', async () => {
|
||||
const service = new taskbuffer.Service('FullBuilder')
|
||||
.critical()
|
||||
.dependsOn('A')
|
||||
.withStart(async () => ({ conn: true }))
|
||||
.withStop(async (inst) => {})
|
||||
.withHealthCheck(async (inst) => inst.conn)
|
||||
.withRetry({ maxRetries: 3 })
|
||||
.withStartupTimeout(5000)
|
||||
.withLabels({ env: 'test' });
|
||||
|
||||
expect(service.criticality).toEqual('critical');
|
||||
expect(service.startupTimeoutMs).toEqual(5000);
|
||||
expect(service.hasLabel('env', 'test')).toBeTrue();
|
||||
});
|
||||
|
||||
export default tap.start();
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@push.rocks/taskbuffer',
|
||||
version: '6.1.2',
|
||||
version: '8.0.0',
|
||||
description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
|
||||
}
|
||||
|
||||
@@ -19,7 +19,8 @@ import type {
|
||||
* .critical()
|
||||
* .dependsOn('Database')
|
||||
* .withStart(async () => { ... })
|
||||
* .withStop(async () => { ... })
|
||||
* .withStop(async (instance) => { ... })
|
||||
* .withHealthCheck(async (instance) => { ... })
|
||||
*
|
||||
* Or extend for complex services:
|
||||
* class MyService extends Service {
|
||||
@@ -37,11 +38,18 @@ export class Service<T = any> {
|
||||
private _dependencies: string[] = [];
|
||||
private _retryConfig: IRetryConfig | undefined;
|
||||
private _healthCheckConfig: IHealthCheckConfig | undefined;
|
||||
private _startupTimeoutMs: number | undefined;
|
||||
|
||||
// Builder-provided functions
|
||||
private _startFn: (() => Promise<T>) | undefined;
|
||||
private _stopFn: (() => Promise<void>) | undefined;
|
||||
private _healthCheckFn: (() => Promise<boolean>) | undefined;
|
||||
private _stopFn: ((instance: T) => Promise<void>) | undefined;
|
||||
private _healthCheckFn: ((instance: T) => Promise<boolean>) | undefined;
|
||||
|
||||
// Instance: the resolved start result
|
||||
private _instance: T | undefined;
|
||||
|
||||
// Labels
|
||||
public labels: Record<string, string> = {};
|
||||
|
||||
// Runtime tracking
|
||||
private _startedAt: number | undefined;
|
||||
@@ -56,6 +64,10 @@ export class Service<T = any> {
|
||||
private _healthCheckOk: boolean | undefined;
|
||||
private _consecutiveHealthFailures = 0;
|
||||
|
||||
// Auto-restart tracking
|
||||
private _autoRestartCount = 0;
|
||||
private _autoRestartTimer: ReturnType<typeof setTimeout> | undefined;
|
||||
|
||||
constructor(nameOrOptions: string | IServiceOptions<T>) {
|
||||
if (typeof nameOrOptions === 'string') {
|
||||
this.name = nameOrOptions;
|
||||
@@ -68,6 +80,10 @@ export class Service<T = any> {
|
||||
this._dependencies = nameOrOptions.dependencies || [];
|
||||
this._retryConfig = nameOrOptions.retry;
|
||||
this._healthCheckConfig = nameOrOptions.healthCheckConfig;
|
||||
this._startupTimeoutMs = nameOrOptions.startupTimeoutMs;
|
||||
if (nameOrOptions.labels) {
|
||||
this.labels = { ...nameOrOptions.labels };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -93,12 +109,12 @@ export class Service<T = any> {
|
||||
return this;
|
||||
}
|
||||
|
||||
public withStop(fn: () => Promise<void>): this {
|
||||
public withStop(fn: (instance: T) => Promise<void>): this {
|
||||
this._stopFn = fn;
|
||||
return this;
|
||||
}
|
||||
|
||||
public withHealthCheck(fn: () => Promise<boolean>, config?: IHealthCheckConfig): this {
|
||||
public withHealthCheck(fn: (instance: T) => Promise<boolean>, config?: IHealthCheckConfig): this {
|
||||
this._healthCheckFn = fn;
|
||||
if (config) {
|
||||
this._healthCheckConfig = config;
|
||||
@@ -111,6 +127,41 @@ export class Service<T = any> {
|
||||
return this;
|
||||
}
|
||||
|
||||
public withStartupTimeout(ms: number): this {
|
||||
this._startupTimeoutMs = ms;
|
||||
return this;
|
||||
}
|
||||
|
||||
public withLabels(labelsArg: Record<string, string>): this {
|
||||
Object.assign(this.labels, labelsArg);
|
||||
return this;
|
||||
}
|
||||
|
||||
// ── Label helpers ──────────────────────────────────
|
||||
|
||||
public setLabel(key: string, value: string): void {
|
||||
this.labels[key] = value;
|
||||
}
|
||||
|
||||
public getLabel(key: string): string | undefined {
|
||||
return this.labels[key];
|
||||
}
|
||||
|
||||
public removeLabel(key: string): boolean {
|
||||
if (key in this.labels) {
|
||||
delete this.labels[key];
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
public hasLabel(key: string, value?: string): boolean {
|
||||
if (value !== undefined) {
|
||||
return this.labels[key] === value;
|
||||
}
|
||||
return key in this.labels;
|
||||
}
|
||||
|
||||
// ── Overridable hooks (for subclassing) ──────────────
|
||||
|
||||
protected async serviceStart(): Promise<T> {
|
||||
@@ -122,14 +173,14 @@ export class Service<T = any> {
|
||||
|
||||
protected async serviceStop(): Promise<void> {
|
||||
if (this._stopFn) {
|
||||
return this._stopFn();
|
||||
return this._stopFn(this._instance as T);
|
||||
}
|
||||
// Default: no-op stop is fine (some services don't need explicit cleanup)
|
||||
}
|
||||
|
||||
protected async serviceHealthCheck(): Promise<boolean> {
|
||||
if (this._healthCheckFn) {
|
||||
return this._healthCheckFn();
|
||||
return this._healthCheckFn(this._instance as T);
|
||||
}
|
||||
// No health check configured — assume healthy if running
|
||||
return this._state === 'running';
|
||||
@@ -139,17 +190,29 @@ export class Service<T = any> {
|
||||
|
||||
public async start(): Promise<T> {
|
||||
if (this._state === 'running') {
|
||||
return undefined as T;
|
||||
return this._instance as T;
|
||||
}
|
||||
|
||||
this.setState('starting');
|
||||
|
||||
try {
|
||||
const result = await this.serviceStart();
|
||||
let result: T;
|
||||
if (this._startupTimeoutMs) {
|
||||
result = await Promise.race([
|
||||
this.serviceStart(),
|
||||
new Promise<never>((_, reject) =>
|
||||
setTimeout(() => reject(new Error(`Service '${this.name}': startup timed out after ${this._startupTimeoutMs}ms`)), this._startupTimeoutMs)
|
||||
),
|
||||
]);
|
||||
} else {
|
||||
result = await this.serviceStart();
|
||||
}
|
||||
this._instance = result;
|
||||
this._startedAt = Date.now();
|
||||
this._stoppedAt = undefined;
|
||||
this._consecutiveHealthFailures = 0;
|
||||
this._healthCheckOk = true;
|
||||
this._autoRestartCount = 0;
|
||||
this.setState('running');
|
||||
this.emitEvent('started');
|
||||
this.startHealthCheckTimer();
|
||||
@@ -169,6 +232,7 @@ export class Service<T = any> {
|
||||
}
|
||||
|
||||
this.stopHealthCheckTimer();
|
||||
this.clearAutoRestartTimer();
|
||||
this.setState('stopping');
|
||||
|
||||
try {
|
||||
@@ -177,6 +241,7 @@ export class Service<T = any> {
|
||||
logger.log('warn', `Service '${this.name}' error during stop: ${err instanceof Error ? err.message : String(err)}`);
|
||||
}
|
||||
|
||||
this._instance = undefined;
|
||||
this._stoppedAt = Date.now();
|
||||
this.setState('stopped');
|
||||
this.emitEvent('stopped');
|
||||
@@ -224,6 +289,65 @@ export class Service<T = any> {
|
||||
}
|
||||
}
|
||||
|
||||
// ── Wait / readiness ──────────────────────────────────
|
||||
|
||||
public async waitForState(
|
||||
targetState: TServiceState | TServiceState[],
|
||||
timeoutMs?: number,
|
||||
): Promise<void> {
|
||||
const states = Array.isArray(targetState) ? targetState : [targetState];
|
||||
|
||||
// Already in target state
|
||||
if (states.includes(this._state)) {
|
||||
return;
|
||||
}
|
||||
|
||||
return new Promise<void>((resolve, reject) => {
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
let settled = false;
|
||||
|
||||
const settle = (fn: () => void) => {
|
||||
if (settled) return;
|
||||
settled = true;
|
||||
subscription.unsubscribe();
|
||||
if (timer) clearTimeout(timer);
|
||||
fn();
|
||||
};
|
||||
|
||||
const subscription = this.eventSubject.subscribe((event) => {
|
||||
if (states.includes(event.state)) {
|
||||
settle(resolve);
|
||||
}
|
||||
});
|
||||
|
||||
// Re-check after subscribing to close the race window
|
||||
if (states.includes(this._state)) {
|
||||
settle(resolve);
|
||||
return;
|
||||
}
|
||||
|
||||
if (timeoutMs !== undefined) {
|
||||
timer = setTimeout(() => {
|
||||
settle(() =>
|
||||
reject(
|
||||
new Error(
|
||||
`Service '${this.name}': timed out waiting for state [${states.join(', ')}] after ${timeoutMs}ms (current: ${this._state})`,
|
||||
),
|
||||
),
|
||||
);
|
||||
}, timeoutMs);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
public async waitForRunning(timeoutMs?: number): Promise<void> {
|
||||
return this.waitForState('running', timeoutMs);
|
||||
}
|
||||
|
||||
public async waitForStopped(timeoutMs?: number): Promise<void> {
|
||||
return this.waitForState('stopped', timeoutMs);
|
||||
}
|
||||
|
||||
// ── State ────────────────────────────────────────────
|
||||
|
||||
public get state(): TServiceState {
|
||||
@@ -242,6 +366,14 @@ export class Service<T = any> {
|
||||
return this._retryConfig;
|
||||
}
|
||||
|
||||
public get startupTimeoutMs(): number | undefined {
|
||||
return this._startupTimeoutMs;
|
||||
}
|
||||
|
||||
public get instance(): T | undefined {
|
||||
return this._instance;
|
||||
}
|
||||
|
||||
public get errorCount(): number {
|
||||
return this._errorCount;
|
||||
}
|
||||
@@ -270,6 +402,8 @@ export class Service<T = any> {
|
||||
lastError: this._lastError,
|
||||
retryCount: this._retryCount,
|
||||
dependencies: [...this._dependencies],
|
||||
labels: { ...this.labels },
|
||||
hasInstance: this._instance !== undefined,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -304,6 +438,54 @@ export class Service<T = any> {
|
||||
this._lastError = `Health check failed ${this._consecutiveHealthFailures} consecutive times`;
|
||||
this.emitEvent('failed', { error: this._lastError });
|
||||
this.stopHealthCheckTimer();
|
||||
|
||||
// Auto-restart if configured
|
||||
if (config?.autoRestart) {
|
||||
this.scheduleAutoRestart();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private scheduleAutoRestart(): void {
|
||||
const config = this._healthCheckConfig;
|
||||
const maxRestarts = config?.maxAutoRestarts ?? 3;
|
||||
if (maxRestarts > 0 && this._autoRestartCount >= maxRestarts) {
|
||||
logger.log('warn', `Service '${this.name}': max auto-restarts (${maxRestarts}) exceeded`);
|
||||
return;
|
||||
}
|
||||
|
||||
const baseDelay = config?.autoRestartDelayMs ?? 5000;
|
||||
const factor = config?.autoRestartBackoffFactor ?? 2;
|
||||
const delay = Math.min(baseDelay * Math.pow(factor, this._autoRestartCount), 60000);
|
||||
|
||||
this._autoRestartCount++;
|
||||
this.emitEvent('autoRestarting', { attempt: this._autoRestartCount });
|
||||
|
||||
this._autoRestartTimer = setTimeout(async () => {
|
||||
this._autoRestartTimer = undefined;
|
||||
try {
|
||||
// Stop first to clean up, then start fresh
|
||||
this._instance = undefined;
|
||||
this._stoppedAt = Date.now();
|
||||
this.setState('stopped');
|
||||
await this.start();
|
||||
// Success — reset counter
|
||||
this._autoRestartCount = 0;
|
||||
} catch (err) {
|
||||
logger.log('warn', `Service '${this.name}': auto-restart attempt ${this._autoRestartCount} failed: ${err instanceof Error ? err.message : String(err)}`);
|
||||
// Schedule another attempt
|
||||
this.scheduleAutoRestart();
|
||||
}
|
||||
}, delay);
|
||||
if (this._autoRestartTimer && typeof this._autoRestartTimer === 'object' && 'unref' in this._autoRestartTimer) {
|
||||
(this._autoRestartTimer as any).unref();
|
||||
}
|
||||
}
|
||||
|
||||
private clearAutoRestartTimer(): void {
|
||||
if (this._autoRestartTimer) {
|
||||
clearTimeout(this._autoRestartTimer);
|
||||
this._autoRestartTimer = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -77,6 +77,23 @@ export class ServiceManager {
|
||||
// Build startup order via topological sort
|
||||
this.startupOrder = this.topologicalSort();
|
||||
this._startedAt = Date.now();
|
||||
|
||||
const startupPromise = this.startAllLevels();
|
||||
|
||||
// Enforce global startup timeout
|
||||
if (this.options.startupTimeoutMs) {
|
||||
await Promise.race([
|
||||
startupPromise,
|
||||
plugins.smartdelay.delayFor(this.options.startupTimeoutMs).then(() => {
|
||||
throw new Error(`${this.name}: global startup timeout exceeded (${this.options.startupTimeoutMs}ms)`);
|
||||
}),
|
||||
]);
|
||||
} else {
|
||||
await startupPromise;
|
||||
}
|
||||
}
|
||||
|
||||
private async startAllLevels(): Promise<void> {
|
||||
const startedServices: string[] = [];
|
||||
|
||||
logger.log('info', `${this.name}: starting ${this.services.size} services in ${this.startupOrder.length} levels`);
|
||||
@@ -178,6 +195,14 @@ export class ServiceManager {
|
||||
return Array.from(this.services.values()).map((s) => s.getStatus());
|
||||
}
|
||||
|
||||
public getServicesByLabel(key: string, value: string): Service[] {
|
||||
return Array.from(this.services.values()).filter((s) => s.labels[key] === value);
|
||||
}
|
||||
|
||||
public getServicesStatusByLabel(key: string, value: string): IServiceStatus[] {
|
||||
return this.getServicesByLabel(key, value).map((s) => s.getStatus());
|
||||
}
|
||||
|
||||
public getHealth(): IServiceManagerHealth {
|
||||
const statuses = this.getAllStatuses();
|
||||
let overall: TOverallHealth = 'healthy';
|
||||
|
||||
@@ -100,7 +100,8 @@ export type TServiceEventType =
|
||||
| 'degraded'
|
||||
| 'recovered'
|
||||
| 'retrying'
|
||||
| 'healthCheck';
|
||||
| 'healthCheck'
|
||||
| 'autoRestarting';
|
||||
|
||||
export interface IServiceEvent {
|
||||
type: TServiceEventType;
|
||||
@@ -124,6 +125,8 @@ export interface IServiceStatus {
|
||||
lastError?: string;
|
||||
retryCount: number;
|
||||
dependencies: string[];
|
||||
labels?: Record<string, string>;
|
||||
hasInstance?: boolean;
|
||||
}
|
||||
|
||||
export interface IRetryConfig {
|
||||
@@ -146,17 +149,27 @@ export interface IHealthCheckConfig {
|
||||
failuresBeforeDegraded?: number;
|
||||
/** Consecutive failures before marking failed. Default: 5 */
|
||||
failuresBeforeFailed?: number;
|
||||
/** Auto-restart the service when it transitions to failed. Default: false */
|
||||
autoRestart?: boolean;
|
||||
/** Maximum number of auto-restart attempts. 0 = unlimited. Default: 3 */
|
||||
maxAutoRestarts?: number;
|
||||
/** Base delay in ms before first auto-restart. Default: 5000 */
|
||||
autoRestartDelayMs?: number;
|
||||
/** Backoff multiplier per auto-restart attempt. Default: 2 */
|
||||
autoRestartBackoffFactor?: number;
|
||||
}
|
||||
|
||||
export interface IServiceOptions<T = any> {
|
||||
name: string;
|
||||
start: () => Promise<T>;
|
||||
stop: () => Promise<void>;
|
||||
healthCheck?: () => Promise<boolean>;
|
||||
stop: (instance: T) => Promise<void>;
|
||||
healthCheck?: (instance: T) => Promise<boolean>;
|
||||
criticality?: TServiceCriticality;
|
||||
dependencies?: string[];
|
||||
retry?: IRetryConfig;
|
||||
healthCheckConfig?: IHealthCheckConfig;
|
||||
startupTimeoutMs?: number;
|
||||
labels?: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface IServiceManagerOptions {
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@push.rocks/taskbuffer',
|
||||
version: '6.1.2',
|
||||
version: '8.0.0',
|
||||
description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user