@aniket-lodh/veyra-sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +209 -120
  2. package/dist/cjs/client.d.ts +204 -0
  3. package/dist/cjs/client.js +647 -0
  4. package/dist/cjs/errors.d.ts +147 -0
  5. package/dist/cjs/errors.js +262 -0
  6. package/dist/cjs/handlers.d.ts +165 -0
  7. package/dist/cjs/handlers.js +46 -0
  8. package/dist/cjs/index.d.ts +15 -0
  9. package/dist/cjs/index.js +37 -0
  10. package/dist/cjs/package.json +3 -0
  11. package/dist/cjs/standard-schema.d.ts +86 -0
  12. package/dist/cjs/standard-schema.js +49 -0
  13. package/dist/cjs/types.d.ts +430 -0
  14. package/dist/cjs/types.js +6 -0
  15. package/dist/cjs/webhook.d.ts +98 -0
  16. package/dist/cjs/webhook.js +165 -0
  17. package/dist/cjs/worker.d.ts +101 -0
  18. package/dist/cjs/worker.js +497 -0
  19. package/dist/client.d.ts +159 -25
  20. package/dist/client.js +501 -122
  21. package/dist/errors.d.ts +123 -10
  22. package/dist/errors.js +192 -19
  23. package/dist/handlers.d.ts +165 -0
  24. package/dist/handlers.js +42 -0
  25. package/dist/index.d.ts +13 -6
  26. package/dist/index.js +12 -6
  27. package/dist/standard-schema.d.ts +86 -0
  28. package/dist/standard-schema.js +45 -0
  29. package/dist/types.d.ts +281 -36
  30. package/dist/types.js +2 -2
  31. package/dist/webhook.d.ts +98 -0
  32. package/dist/webhook.js +128 -0
  33. package/dist/worker.d.ts +80 -55
  34. package/dist/worker.js +308 -195
  35. package/package.json +27 -13
  36. package/dist/client.d.ts.map +0 -1
  37. package/dist/client.js.map +0 -1
  38. package/dist/errors.d.ts.map +0 -1
  39. package/dist/errors.js.map +0 -1
  40. package/dist/index.d.ts.map +0 -1
  41. package/dist/index.js.map +0 -1
  42. package/dist/types.d.ts.map +0 -1
  43. package/dist/types.js.map +0 -1
  44. package/dist/worker.d.ts.map +0 -1
  45. package/dist/worker.js.map +0 -1
  46. package/src/client.ts +0 -389
  47. package/src/errors.ts +0 -82
  48. package/src/index.ts +0 -8
  49. package/src/types.ts +0 -217
  50. package/src/worker.ts +0 -472
@@ -0,0 +1,497 @@
1
+ "use strict";
2
+ /**
3
+ * Veyra HTTP worker engine.
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.VeyraWorker = void 0;
7
+ const errors_js_1 = require("./errors.js");
8
+ const standard_schema_js_1 = require("./standard-schema.js");
9
+ function unrefTimer(timer) {
10
+ const maybe = timer;
11
+ if (typeof maybe?.unref === 'function') {
12
+ maybe.unref();
13
+ }
14
+ }
15
+ /**
16
+ * Long-polling worker that registers with Veyra, claims jobs, renews leases,
17
+ * executes handlers, and reports outcomes.
18
+ *
19
+ * @typeParam THandlers - Extra handler contracts merged over {@link BuiltInHandlers}.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * const worker = client.createWorker({ queues: ['default'] });
24
+ * worker.register(sendEmail, async (job) => ({ messageId: await send(job.payload) }));
25
+ * await worker.start();
26
+ * ```
27
+ */
28
+ class VeyraWorker {
29
+ #client;
30
+ #options;
31
+ #handlers = new Map();
32
+ #workerId;
33
+ #state = 'stopped';
34
+ #inFlight = 0;
35
+ #activeLeaseTimers = new Map();
36
+ #activeAbortControllers = new Map();
37
+ #heartbeatTimer;
38
+ #pollTimeout;
39
+ #drainResolver;
40
+ #isRegistering = false;
41
+ #consecutivePollErrors = 0;
42
+ /**
43
+ * @param client - Client used for API calls.
44
+ * @param options - Queues, concurrency, timings, and lifecycle callbacks.
45
+ * @throws {VeyraValidationError} When options fail validation.
46
+ */
47
+ constructor(client, options) {
48
+ if (!options || typeof options !== 'object') {
49
+ throw new errors_js_1.VeyraValidationError('options', [{ message: 'VeyraWorkerOptions must be an object' }]);
50
+ }
51
+ if (!Array.isArray(options.queues) || options.queues.length === 0) {
52
+ throw new errors_js_1.VeyraValidationError('queues', [{ message: 'queues must be a non-empty array of queue names' }]);
53
+ }
54
+ const queues = options.queues.map((q, idx) => {
55
+ if (typeof q !== 'string' || !q.trim()) {
56
+ throw new errors_js_1.VeyraValidationError(`queues[${idx}]`, [{ message: 'queue name must be a non-empty string' }]);
57
+ }
58
+ return q.trim();
59
+ });
60
+ const concurrency = options.concurrency ?? 5;
61
+ if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 1000) {
62
+ throw new errors_js_1.VeyraValidationError('concurrency', [{ message: 'concurrency must be an integer between 1 and 1000' }]);
63
+ }
64
+ const pollIntervalMs = options.pollIntervalMs ?? 1_000;
65
+ if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
66
+ throw new errors_js_1.VeyraValidationError('pollIntervalMs', [{ message: 'pollIntervalMs must be a positive finite number' }]);
67
+ }
68
+ const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 10_000;
69
+ if (!Number.isFinite(heartbeatIntervalMs) || heartbeatIntervalMs <= 0) {
70
+ throw new errors_js_1.VeyraValidationError('heartbeatIntervalMs', [{ message: 'heartbeatIntervalMs must be a positive finite number' }]);
71
+ }
72
+ const leaseHeartbeatIntervalMs = options.leaseHeartbeatIntervalMs ?? 10_000;
73
+ if (!Number.isFinite(leaseHeartbeatIntervalMs) || leaseHeartbeatIntervalMs <= 0) {
74
+ throw new errors_js_1.VeyraValidationError('leaseHeartbeatIntervalMs', [{ message: 'leaseHeartbeatIntervalMs must be a positive finite number' }]);
75
+ }
76
+ this.#client = client;
77
+ this.#options = {
78
+ ...options,
79
+ queues,
80
+ concurrency,
81
+ pollIntervalMs,
82
+ heartbeatIntervalMs,
83
+ leaseHeartbeatIntervalMs,
84
+ };
85
+ this.#workerId =
86
+ this.#options.workerId?.trim() ||
87
+ `worker-${Math.random().toString(36).substring(2, 10)}`;
88
+ }
89
+ /** Worker id used on every worker-protocol call. */
90
+ get workerId() {
91
+ return this.#workerId;
92
+ }
93
+ /** Current lifecycle state. */
94
+ get state() {
95
+ return this.#state;
96
+ }
97
+ /** Number of jobs currently executing. */
98
+ get inFlight() {
99
+ return this.#inFlight;
100
+ }
101
+ /** Bound client. */
102
+ get client() {
103
+ return this.#client;
104
+ }
105
+ /** Resolved worker options. */
106
+ get options() {
107
+ return { ...this.#options };
108
+ }
109
+ /** Registered handlers map view. */
110
+ get handlers() {
111
+ return new Map(this.#handlers);
112
+ }
113
+ /**
114
+ * Safe JSON representation redacting all sensitive credentials.
115
+ */
116
+ toJSON() {
117
+ return {
118
+ workerId: this.#workerId,
119
+ state: this.#state,
120
+ inFlight: this.#inFlight,
121
+ queues: [...this.#options.queues],
122
+ concurrency: this.#options.concurrency,
123
+ handlers: Array.from(this.#handlers.keys()),
124
+ };
125
+ }
126
+ /**
127
+ * Node.js custom inspection hook redacting all sensitive credentials from console output.
128
+ */
129
+ [Symbol.for('nodejs.util.inspect.custom')]() {
130
+ return this.toJSON();
131
+ }
132
+ register(nameOrDefinition, handler) {
133
+ if (typeof nameOrDefinition === 'string') {
134
+ return this.#setHandler(nameOrDefinition, handler);
135
+ }
136
+ const definition = nameOrDefinition;
137
+ const wrapped = async (job, ctx) => {
138
+ const payload = await (0, standard_schema_js_1.validateWithSchema)(definition.payload, job.payload, `handler '${definition.name}' payload`);
139
+ const result = await handler({ ...job, payload }, ctx);
140
+ return (0, standard_schema_js_1.validateWithSchema)(definition.result, result, `handler '${definition.name}' result`);
141
+ };
142
+ return this.#setHandler(definition.name, wrapped);
143
+ }
144
+ /**
145
+ * Registers a handler by name without a definition. Prefer {@link register}
146
+ * with a `defineHandler` definition for payload/result typing.
147
+ *
148
+ * @param name - Handler name matched against claimed jobs.
149
+ * @param handler - Callback receiving the claimed job and context.
150
+ * @throws {VeyraError} When a handler with the same name is already registered.
151
+ */
152
+ registerHandler(name, handler) {
153
+ return this.#setHandler(name, handler);
154
+ }
155
+ /**
156
+ * Returns the handler names advertised at registration.
157
+ * Defaults to every registered handler when `options.handlers` is empty.
158
+ */
159
+ getEffectiveHandlers() {
160
+ if (this.#options.handlers && this.#options.handlers.length > 0) {
161
+ return [...this.#options.handlers];
162
+ }
163
+ return Array.from(this.#handlers.keys());
164
+ }
165
+ /**
166
+ * Registers with Veyra, starts heartbeats, and begins claiming jobs.
167
+ *
168
+ * @returns The worker record stored by the API.
169
+ * @throws {VeyraError} When already running or no handlers are registered.
170
+ */
171
+ async start() {
172
+ if (this.#state === 'running') {
173
+ throw new errors_js_1.VeyraError('VeyraWorker is already running', { code: 'ALREADY_RUNNING' });
174
+ }
175
+ const effectiveHandlers = this.getEffectiveHandlers();
176
+ if (effectiveHandlers.length === 0) {
177
+ throw new errors_js_1.VeyraError('VeyraWorker: No handlers registered. Call register() or registerHandler() before starting.');
178
+ }
179
+ this.#state = 'running';
180
+ const record = await this.#registerWorkerRecord();
181
+ this.#startWorkerHeartbeatLoop();
182
+ this.#triggerClaimLoop();
183
+ return record;
184
+ }
185
+ /**
186
+ * Stops claiming, drains in-flight jobs, cancels timers, and deregisters.
187
+ *
188
+ * @param options.timeoutMs - Maximum drain wait. Defaults to `30000`.
189
+ */
190
+ async stop(options) {
191
+ if (this.#state === 'stopped') {
192
+ return;
193
+ }
194
+ this.#state = 'draining';
195
+ if (this.#pollTimeout) {
196
+ clearTimeout(this.#pollTimeout);
197
+ this.#pollTimeout = undefined;
198
+ }
199
+ try {
200
+ await this.#client.drainWorker(this.#workerId);
201
+ }
202
+ catch (err) {
203
+ this.#options.onError?.(err);
204
+ this.#options.logger?.warn?.(`Worker drain failed for ${this.#workerId}`, {
205
+ error: err.message,
206
+ });
207
+ }
208
+ const timeoutMs = options?.timeoutMs ?? 30_000;
209
+ if (this.#inFlight > 0) {
210
+ await Promise.race([
211
+ new Promise((resolve) => {
212
+ this.#drainResolver = resolve;
213
+ }),
214
+ new Promise((_, reject) => setTimeout(() => reject(new errors_js_1.VeyraError(`Worker drain timed out after ${timeoutMs}ms with ${this.#inFlight} jobs remaining`)), timeoutMs)),
215
+ ]).catch((err) => {
216
+ this.#options.onError?.(err);
217
+ });
218
+ }
219
+ if (this.#heartbeatTimer) {
220
+ clearInterval(this.#heartbeatTimer);
221
+ this.#heartbeatTimer = undefined;
222
+ }
223
+ for (const [, timer] of this.#activeLeaseTimers) {
224
+ clearInterval(timer);
225
+ }
226
+ this.#activeLeaseTimers.clear();
227
+ this.#activeAbortControllers.clear();
228
+ try {
229
+ await this.#client.deregisterWorker(this.#workerId);
230
+ }
231
+ catch (err) {
232
+ this.#options.onError?.(err);
233
+ this.#options.logger?.warn?.(`Worker deregister failed for ${this.#workerId}`, {
234
+ error: err.message,
235
+ });
236
+ }
237
+ this.#state = 'stopped';
238
+ this.#drainResolver = undefined;
239
+ }
240
+ #setHandler(name, handler) {
241
+ const trimmed = name.trim();
242
+ if (!trimmed) {
243
+ throw new errors_js_1.VeyraValidationError('name', [{ message: 'Handler name must not be empty' }]);
244
+ }
245
+ if (this.#handlers.has(trimmed)) {
246
+ throw new errors_js_1.VeyraError(`Handler '${trimmed}' is already registered on this worker. Registering multiple handlers with the same name is not allowed.`, { code: 'DUPLICATE_HANDLER' });
247
+ }
248
+ this.#handlers.set(trimmed, handler);
249
+ return this;
250
+ }
251
+ async #registerWorkerRecord() {
252
+ if (this.#isRegistering) {
253
+ return {};
254
+ }
255
+ this.#isRegistering = true;
256
+ try {
257
+ const proc = typeof globalThis !== 'undefined'
258
+ ? globalThis.process
259
+ : undefined;
260
+ const effectiveHandlers = this.getEffectiveHandlers();
261
+ const record = await this.#client.registerWorker({
262
+ id: this.#workerId,
263
+ hostname: this.#options.hostname || proc?.env?.HOSTNAME || 'external-sdk',
264
+ pid: this.#options.pid || proc?.pid || 0,
265
+ version: this.#options.version || '0.1.0',
266
+ queues: this.#options.queues,
267
+ handlers: effectiveHandlers,
268
+ maxConcurrency: this.#options.concurrency ?? 5,
269
+ heartbeatIntervalSeconds: Math.max(1, Math.floor((this.#options.heartbeatIntervalMs ?? 10_000) / 1000)),
270
+ });
271
+ if (record?.id) {
272
+ this.#workerId = record.id;
273
+ }
274
+ return record;
275
+ }
276
+ finally {
277
+ this.#isRegistering = false;
278
+ }
279
+ }
280
+ #startWorkerHeartbeatLoop() {
281
+ if (this.#heartbeatTimer) {
282
+ clearInterval(this.#heartbeatTimer);
283
+ }
284
+ const interval = this.#options.heartbeatIntervalMs ?? 10_000;
285
+ this.#heartbeatTimer = setInterval(async () => {
286
+ if (this.#state === 'stopped') {
287
+ return;
288
+ }
289
+ try {
290
+ await this.#client.heartbeatWorker(this.#workerId);
291
+ }
292
+ catch (err) {
293
+ if (err instanceof errors_js_1.VeyraNotFoundError) {
294
+ try {
295
+ await this.#registerWorkerRecord();
296
+ }
297
+ catch (regErr) {
298
+ this.#options.onError?.(regErr);
299
+ this.#options.logger?.error?.('Worker re-registration failed', {
300
+ error: regErr.message,
301
+ });
302
+ }
303
+ }
304
+ else {
305
+ this.#options.onError?.(err);
306
+ this.#options.logger?.warn?.('Worker heartbeat failed', {
307
+ error: err.message,
308
+ });
309
+ }
310
+ }
311
+ }, interval);
312
+ unrefTimer(this.#heartbeatTimer);
313
+ }
314
+ #triggerClaimLoop(delayMs = 0) {
315
+ if (this.#state !== 'running') {
316
+ return;
317
+ }
318
+ if (this.#pollTimeout) {
319
+ clearTimeout(this.#pollTimeout);
320
+ }
321
+ this.#pollTimeout = setTimeout(() => {
322
+ this.#pollTimeout = undefined;
323
+ void this.#claimAndDispatch();
324
+ }, delayMs);
325
+ unrefTimer(this.#pollTimeout);
326
+ }
327
+ async #claimAndDispatch() {
328
+ if (this.#state !== 'running') {
329
+ return;
330
+ }
331
+ const maxConcurrency = this.#options.concurrency ?? 5;
332
+ if (this.#inFlight >= maxConcurrency) {
333
+ return;
334
+ }
335
+ const effectiveHandlers = this.getEffectiveHandlers();
336
+ let claimResult = null;
337
+ try {
338
+ claimResult = await this.#client.claimJob(this.#workerId, {
339
+ queues: this.#options.queues,
340
+ handlers: effectiveHandlers,
341
+ });
342
+ this.#consecutivePollErrors = 0;
343
+ }
344
+ catch (err) {
345
+ this.#consecutivePollErrors++;
346
+ const baseDelay = this.#options.pollIntervalMs ?? 1_000;
347
+ const backoffDelay = Math.min(30_000, baseDelay * Math.pow(1.5, Math.min(this.#consecutivePollErrors, 10)));
348
+ if (err instanceof errors_js_1.VeyraNotFoundError) {
349
+ try {
350
+ await this.#registerWorkerRecord();
351
+ this.#triggerClaimLoop(100);
352
+ return;
353
+ }
354
+ catch (regErr) {
355
+ this.#options.onError?.(regErr);
356
+ this.#options.logger?.error?.('Worker re-registration failed', {
357
+ error: regErr.message,
358
+ });
359
+ }
360
+ }
361
+ else {
362
+ this.#options.onError?.(err);
363
+ this.#options.logger?.warn?.(`Worker claim failed, backing off for ${Math.round(backoffDelay)}ms`, { error: err.message, consecutiveErrors: this.#consecutivePollErrors });
364
+ }
365
+ this.#triggerClaimLoop(backoffDelay);
366
+ return;
367
+ }
368
+ if (!claimResult) {
369
+ this.#triggerClaimLoop(this.#options.pollIntervalMs ?? 1_000);
370
+ return;
371
+ }
372
+ this.#inFlight++;
373
+ this.#options.onJobStart?.(claimResult);
374
+ void this.#executeJob(claimResult).finally(() => {
375
+ this.#inFlight--;
376
+ if (this.#state === 'draining' && this.#inFlight === 0) {
377
+ this.#drainResolver?.();
378
+ }
379
+ else if (this.#state === 'running') {
380
+ this.#triggerClaimLoop(0);
381
+ }
382
+ });
383
+ if (this.#inFlight < maxConcurrency && this.#state === 'running') {
384
+ this.#triggerClaimLoop(0);
385
+ }
386
+ }
387
+ async #executeJob(job) {
388
+ const abortController = new AbortController();
389
+ this.#activeAbortControllers.set(job.id, abortController);
390
+ this.#startJobLeaseRenewal(job.id, abortController);
391
+ const ctx = {
392
+ jobId: job.id,
393
+ attempt: job.attempt,
394
+ queue: job.queue,
395
+ handler: job.handler,
396
+ signal: abortController.signal,
397
+ extendLease: async () => {
398
+ return this.#client.renewJobLease(this.#workerId, job.id);
399
+ },
400
+ };
401
+ const handlerFn = this.#handlers.get(job.handler);
402
+ try {
403
+ if (!handlerFn) {
404
+ throw new errors_js_1.VeyraError(`No registered handler found for '${job.handler}'`);
405
+ }
406
+ const result = await handlerFn(job, ctx);
407
+ this.#stopJobLeaseRenewal(job.id);
408
+ await this.#client.completeJob(this.#workerId, job.id, result);
409
+ this.#options.onJobComplete?.(job, result);
410
+ }
411
+ catch (err) {
412
+ this.#stopJobLeaseRenewal(job.id);
413
+ // SPEC §1.2 / §4: If the job lease was lost/expired, the worker context was aborted.
414
+ // Do not ack or nack: leave the lease to expire cleanly so the queue supervisor reclaims it.
415
+ if (abortController.signal.aborted &&
416
+ abortController.signal.reason instanceof errors_js_1.LeaseLostError) {
417
+ this.#options.onJobError?.(job, abortController.signal.reason);
418
+ return;
419
+ }
420
+ const permanent = (0, errors_js_1.isNonRetryable)(err);
421
+ const errorClass = err?.name ||
422
+ err?.errorClass ||
423
+ 'HandlerError';
424
+ const rawMessage = err instanceof Error
425
+ ? err.message
426
+ : typeof err === 'string'
427
+ ? err
428
+ : 'Job execution failed';
429
+ const message = rawMessage.length > 1000 ? `${rawMessage.slice(0, 1000)}...` : rawMessage;
430
+ const rawStack = err instanceof Error ? err.stack : undefined;
431
+ const stackTrace = rawStack && rawStack.length > 4000 ? `${rawStack.slice(0, 4000)}...` : rawStack;
432
+ try {
433
+ await this.#client.failJob(this.#workerId, job.id, {
434
+ errorClass,
435
+ message,
436
+ stackTrace,
437
+ permanent,
438
+ });
439
+ }
440
+ catch (reportErr) {
441
+ this.#options.onError?.(reportErr);
442
+ this.#options.logger?.error?.(`Failed reporting job ${job.id} failure to API`, {
443
+ error: reportErr.message,
444
+ });
445
+ }
446
+ this.#options.onJobError?.(job, err);
447
+ }
448
+ finally {
449
+ this.#stopJobLeaseRenewal(job.id);
450
+ this.#activeAbortControllers.delete(job.id);
451
+ }
452
+ }
453
+ #startJobLeaseRenewal(jobId, abortController) {
454
+ const interval = this.#options.leaseHeartbeatIntervalMs ?? 10_000;
455
+ const timer = setInterval(async () => {
456
+ try {
457
+ await this.#client.renewJobLease(this.#workerId, jobId);
458
+ }
459
+ catch (err) {
460
+ if (err instanceof errors_js_1.LeaseLostError ||
461
+ err instanceof errors_js_1.VeyraConflictError ||
462
+ err?.status === 409) {
463
+ this.#stopJobLeaseRenewal(jobId);
464
+ abortController.abort(new errors_js_1.LeaseLostError(`Lease lost for job ${jobId}; stopping execution.`));
465
+ return;
466
+ }
467
+ if (err instanceof errors_js_1.VeyraNotFoundError) {
468
+ try {
469
+ await this.#registerWorkerRecord();
470
+ }
471
+ catch (regErr) {
472
+ this.#options.onError?.(regErr);
473
+ this.#options.logger?.error?.('Worker re-registration failed', {
474
+ error: regErr.message,
475
+ });
476
+ }
477
+ }
478
+ else {
479
+ this.#options.onError?.(err);
480
+ this.#options.logger?.warn?.(`Job ${jobId} lease renewal failed`, {
481
+ error: err.message,
482
+ });
483
+ }
484
+ }
485
+ }, interval);
486
+ unrefTimer(timer);
487
+ this.#activeLeaseTimers.set(jobId, timer);
488
+ }
489
+ #stopJobLeaseRenewal(jobId) {
490
+ const timer = this.#activeLeaseTimers.get(jobId);
491
+ if (timer) {
492
+ clearInterval(timer);
493
+ this.#activeLeaseTimers.delete(jobId);
494
+ }
495
+ }
496
+ }
497
+ exports.VeyraWorker = VeyraWorker;