navi-hey 1.1.0 → 1.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 (85) hide show
  1. package/README.md +38 -4
  2. package/lib/enqueuers/ActionEnqueuer.js +18 -2
  3. package/lib/enqueuers/ActionsEnqueuer.js +6 -3
  4. package/lib/enqueuers/PaginatedActionEnqueuer.js +53 -0
  5. package/lib/enqueuers/PaginatedActionsEnqueuer.js +47 -0
  6. package/lib/exceptions/{ConfigurationFileNotFound.js → config/ConfigurationFileNotFound.js} +1 -1
  7. package/lib/exceptions/{ConfigurationFileNotProvided.js → config/ConfigurationFileNotProvided.js} +1 -1
  8. package/lib/exceptions/{MissingTopLevelConfgKey.js → config/MissingTopLevelConfgKey.js} +1 -1
  9. package/lib/exceptions/{ConflictError.js → http/ConflictError.js} +1 -1
  10. package/lib/exceptions/{ForbiddenError.js → http/ForbiddenError.js} +1 -1
  11. package/lib/exceptions/{NotFoundError.js → http/NotFoundError.js} +1 -1
  12. package/lib/exceptions/{ItemNotFound.js → registry/ItemNotFound.js} +1 -1
  13. package/lib/exceptions/{MissingActionResource.js → registry/MissingActionResource.js} +1 -1
  14. package/lib/exceptions/{MissingMappingVariable.js → registry/MissingMappingVariable.js} +1 -1
  15. package/lib/exceptions/{InvalidHtmlResponseBody.js → request/InvalidHtmlResponseBody.js} +1 -1
  16. package/lib/exceptions/{InvalidResponseBody.js → request/InvalidResponseBody.js} +1 -1
  17. package/lib/exceptions/{NullResponse.js → request/NullResponse.js} +1 -1
  18. package/lib/exceptions/{RequestFailed.js → request/RequestFailed.js} +1 -1
  19. package/lib/jobs/ActionProcessingJob.js +17 -3
  20. package/lib/jobs/HtmlParseJob.js +17 -4
  21. package/lib/jobs/PaginatedActionProcessingJob.js +77 -0
  22. package/lib/jobs/ResourceRequestJob.js +8 -5
  23. package/lib/models/{Config.js → configs/Config.js} +3 -3
  24. package/lib/models/configs/PaginationConfig.js +63 -0
  25. package/lib/models/{ResourceRequest.js → request/ResourceRequest.js} +30 -8
  26. package/lib/models/{ResourceRequestAction.js → request/ResourceRequestAction.js} +6 -6
  27. package/lib/models/request/ResourceRequestPaginatedAction.js +81 -0
  28. package/lib/models/{PathSegmentTraverser.js → response/PathSegmentTraverser.js} +1 -1
  29. package/lib/models/{ResponseParser.js → response/ResponseParser.js} +1 -1
  30. package/lib/registry/ClientRegistry.js +1 -1
  31. package/lib/registry/LogRegistry.js +13 -13
  32. package/lib/registry/LogRegistryInstance.js +16 -16
  33. package/lib/registry/NamedRegistry.js +1 -1
  34. package/lib/registry/ResourceRegistry.js +1 -1
  35. package/lib/serializers/JobIndexSerializer.js +3 -0
  36. package/lib/serializers/LogSerializer.js +1 -1
  37. package/lib/server/PathValidator.js +1 -1
  38. package/lib/server/RouteRegister.js +3 -3
  39. package/lib/server/Router.js +18 -18
  40. package/lib/server/{AssetsRequestHandler.js → handlers/AssetsRequestHandler.js} +3 -3
  41. package/lib/server/{BaseUrlsRequestHandler.js → handlers/BaseUrlsRequestHandler.js} +3 -3
  42. package/lib/server/{IndexRequestHandler.js → handlers/IndexRequestHandler.js} +2 -2
  43. package/lib/server/{JobsFilter.js → handlers/JobsFilter.js} +1 -1
  44. package/lib/server/{LogsRequestHandler.js → handlers/LogsRequestHandler.js} +4 -4
  45. package/lib/server/{SettingsRequestHandler.js → handlers/SettingsRequestHandler.js} +4 -3
  46. package/lib/server/{StatsRequestHandler.js → handlers/StatsRequestHandler.js} +3 -3
  47. package/lib/server/{EngineContinueRequestHandler.js → handlers/engine/EngineContinueRequestHandler.js} +3 -3
  48. package/lib/server/{EnginePauseRequestHandler.js → handlers/engine/EnginePauseRequestHandler.js} +3 -3
  49. package/lib/server/{EngineRestartRequestHandler.js → handlers/engine/EngineRestartRequestHandler.js} +3 -3
  50. package/lib/server/{EngineShutdownRequestHandler.js → handlers/engine/EngineShutdownRequestHandler.js} +2 -2
  51. package/lib/server/{EngineStartRequestHandler.js → handlers/engine/EngineStartRequestHandler.js} +3 -3
  52. package/lib/server/{EngineStatusRequestHandler.js → handlers/engine/EngineStatusRequestHandler.js} +2 -2
  53. package/lib/server/{EngineStopRequestHandler.js → handlers/engine/EngineStopRequestHandler.js} +3 -3
  54. package/lib/server/{JobLogsRequestHandler.js → handlers/jobs/JobLogsRequestHandler.js} +4 -4
  55. package/lib/server/{JobRequestHandler.js → handlers/jobs/JobRequestHandler.js} +4 -4
  56. package/lib/server/{JobRetryRequestHandler.js → handlers/jobs/JobRetryRequestHandler.js} +4 -4
  57. package/lib/server/{JobsRequestHandler.js → handlers/jobs/JobsRequestHandler.js} +4 -4
  58. package/lib/services/ApplicationInstance.js +4 -2
  59. package/lib/services/Client.js +1 -1
  60. package/lib/services/ConfigLoader.js +1 -1
  61. package/lib/services/ConfigParser.js +7 -7
  62. package/lib/services/Engine.js +1 -1
  63. package/lib/utils/HtmlParser.js +1 -1
  64. package/lib/utils/logging/BufferedLogger.js +1 -1
  65. package/lib/utils/logging/LogBuffer.js +1 -1
  66. package/lib/utils/logging/LogBufferCollection.js +1 -1
  67. package/lib/utils/logging/LogFilter.js +2 -2
  68. package/package.json +1 -1
  69. package/static/assets/index-D5tOOLpl.js +11 -0
  70. package/static/index.html +1 -1
  71. package/lib/exceptions/LockedByOtherWorker.js +0 -14
  72. package/static/assets/index-BfggoMvd.js +0 -11
  73. /package/lib/exceptions/{MissingClientsConfig.js → config/MissingClientsConfig.js} +0 -0
  74. /package/lib/exceptions/{MissingResourceConfig.js → config/MissingResourceConfig.js} +0 -0
  75. /package/lib/exceptions/{ClientNotFound.js → registry/ClientNotFound.js} +0 -0
  76. /package/lib/exceptions/{ResourceNotFound.js → registry/ResourceNotFound.js} +0 -0
  77. /package/lib/models/{FailureConfig.js → configs/FailureConfig.js} +0 -0
  78. /package/lib/models/{LogConfig.js → configs/LogConfig.js} +0 -0
  79. /package/lib/models/{WebConfig.js → configs/WebConfig.js} +0 -0
  80. /package/lib/models/{WorkersConfig.js → configs/WorkersConfig.js} +0 -0
  81. /package/lib/models/{AssetRequest.js → request/AssetRequest.js} +0 -0
  82. /package/lib/models/{Resource.js → request/Resource.js} +0 -0
  83. /package/lib/models/{ParametersMapper.js → response/ParametersMapper.js} +0 -0
  84. /package/lib/models/{PathResolver.js → response/PathResolver.js} +0 -0
  85. /package/lib/models/{ResponseWrapper.js → response/ResponseWrapper.js} +0 -0
@@ -1,8 +1,10 @@
1
1
  import { AssetRequest } from './AssetRequest.js';
2
2
  import { ResourceRequestAction } from './ResourceRequestAction.js';
3
- import { JobRegistry as DefaultJobRegistry } from '../background/JobRegistry.js';
4
- import { ActionsEnqueuer } from '../enqueuers/ActionsEnqueuer.js';
5
- import { Application } from '../services/Application.js';
3
+ import { ResourceRequestPaginatedAction } from './ResourceRequestPaginatedAction.js';
4
+ import { JobRegistry as DefaultJobRegistry } from '../../background/JobRegistry.js';
5
+ import { ActionsEnqueuer } from '../../enqueuers/ActionsEnqueuer.js';
6
+ import { PaginatedActionsEnqueuer } from '../../enqueuers/PaginatedActionsEnqueuer.js';
7
+ import { Application } from '../../services/Application.js';
6
8
 
7
9
  /**
8
10
  * ResourceRequest represents a request to a specific URL with an expected status code.
@@ -18,13 +20,15 @@ class ResourceRequest {
18
20
  * @param {string} [attributes.clientName] The name of the client to use for this request.
19
21
  * @param {Array} [attributes.actions=[]] List of raw action config objects.
20
22
  * @param {Array} [attributes.assets=[]] List of raw asset extraction rule objects.
23
+ * @param {Array} [attributes.paginated_actions=[]] List of raw paginated action config objects.
21
24
  */
22
- constructor({ url, status, clientName, actions = [], assets = [] }) {
25
+ constructor({ url, status, clientName, actions = [], assets = [], paginated_actions = [] }) {
23
26
  this.url = url;
24
27
  this.status = status;
25
28
  this.#clientName = clientName;
26
29
  this.actions = ResourceRequestAction.fromList(actions);
27
30
  this.assets = AssetRequest.fromListObject(assets);
31
+ this.paginatedActions = ResourceRequestPaginatedAction.fromList(paginated_actions);
28
32
  }
29
33
 
30
34
  /**
@@ -40,13 +44,28 @@ class ResourceRequest {
40
44
  * Enqueues one ActionProcessingJob per action associated with the resource request.
41
45
  * Returns immediately if there are no actions.
42
46
  * @param {ResponseWrapper} responseWrapper The ResponseWrapper for the HTTP response.
47
+ * @param {string|null} [originUrl=null] The URL of the ResourceRequestJob that triggered this enqueue.
43
48
  * @returns {void}
44
49
  */
45
- enqueueActions(responseWrapper) {
50
+ enqueueActions(responseWrapper, originUrl = null) {
46
51
  if (this.actions.length === 0) return;
47
52
 
48
53
  const itemWrappers = responseWrapper.toItemWrappers();
49
- new ActionsEnqueuer(this.actions, itemWrappers).enqueue();
54
+ new ActionsEnqueuer(this.actions, itemWrappers, undefined, originUrl).enqueue();
55
+ }
56
+
57
+ /**
58
+ * Enqueues one PaginatedActionProcessingJob per paginated action.
59
+ * Returns immediately if there are no paginated actions.
60
+ * @param {ResponseWrapper} responseWrapper The ResponseWrapper for the HTTP response.
61
+ * @param {object} [parameters={}] The original request parameters (key-value map for URL template resolution).
62
+ * @param {string|null} [originUrl=null] The URL of the ResourceRequestJob that triggered this enqueue.
63
+ * @returns {void}
64
+ */
65
+ enqueuePaginatedActions(responseWrapper, parameters = {}, originUrl = null) {
66
+ if (this.paginatedActions.length === 0) return;
67
+
68
+ new PaginatedActionsEnqueuer(this.paginatedActions, responseWrapper, parameters, undefined, originUrl).enqueue();
50
69
  }
51
70
 
52
71
  /**
@@ -55,11 +74,14 @@ class ResourceRequest {
55
74
  * @param {string} rawHtml The raw HTML response body string.
56
75
  * @param {object} [jobRegistry=JobRegistry] The job registry used to enqueue the HtmlParseJob.
57
76
  * @param {object} clientRegistry The client registry for URL resolution inside HtmlParseJob.
77
+ * @param {string|null} [originUrl=null] The URL of the ResourceRequestJob that triggered this enqueue.
58
78
  * @returns {void}
59
79
  */
60
- enqueueAssets(rawHtml, jobRegistry = DefaultJobRegistry, clientRegistry) {
80
+ enqueueAssets(rawHtml, jobRegistry = DefaultJobRegistry, clientRegistry, originUrl = null) {
61
81
  if (Application.isStopped()) return;
62
- jobRegistry.enqueue('HtmlParse', { rawHtml, assetRequests: this.assets, clientRegistry });
82
+ const params = { rawHtml, assetRequests: this.assets, clientRegistry };
83
+ if (originUrl !== null) params.originUrl = originUrl;
84
+ jobRegistry.enqueue('HtmlParse', params);
63
85
  }
64
86
 
65
87
  /**
@@ -1,9 +1,9 @@
1
- import { ParametersMapper } from './ParametersMapper.js';
2
- import { JobRegistry as DefaultJobRegistry } from '../background/JobRegistry.js';
3
- import { MissingActionResource } from '../exceptions/MissingActionResource.js';
4
- import { LogRegistry } from '../registry/LogRegistry.js';
5
- import { ResourceRegistry as DefaultResourceRegistry } from '../registry/ResourceRegistry.js';
6
- import { Application } from '../services/Application.js';
1
+ import { JobRegistry as DefaultJobRegistry } from '../../background/JobRegistry.js';
2
+ import { MissingActionResource } from '../../exceptions/registry/MissingActionResource.js';
3
+ import { LogRegistry } from '../../registry/LogRegistry.js';
4
+ import { ResourceRegistry as DefaultResourceRegistry } from '../../registry/ResourceRegistry.js';
5
+ import { Application } from '../../services/Application.js';
6
+ import { ParametersMapper } from '../response/ParametersMapper.js';
7
7
 
8
8
  /**
9
9
  * Represents a single action to execute after a successful resource request response.
@@ -0,0 +1,81 @@
1
+ import { JobRegistry as DefaultJobRegistry } from '../../background/JobRegistry.js';
2
+ import { MissingActionResource } from '../../exceptions/registry/MissingActionResource.js';
3
+ import { LogRegistry } from '../../registry/LogRegistry.js';
4
+ import { ResourceRegistry as DefaultResourceRegistry } from '../../registry/ResourceRegistry.js';
5
+ import { Application } from '../../services/Application.js';
6
+ import { PaginationConfig } from '../configs/PaginationConfig.js';
7
+
8
+ /**
9
+ * Represents a single paginated action to execute after a successful resource request response.
10
+ *
11
+ * Iterates over pages and enqueues one ResourceRequestJob per page, merging the page number
12
+ * into the item's existing parameters.
13
+ * @author darthjee
14
+ */
15
+ class ResourceRequestPaginatedAction {
16
+ #resource;
17
+ #pagination;
18
+ #jobRegistry;
19
+ #resourceRegistry;
20
+
21
+ /**
22
+ * @param {object} attributes Action attributes.
23
+ * @param {string} attributes.resource Name of the resource to act upon.
24
+ * @param {Array<object>} attributes.pagination Pagination config list.
25
+ * @param {object} [attributes.jobRegistry=JobRegistry] The job registry to enqueue jobs to.
26
+ * @param {object} [attributes.resourceRegistry=ResourceRegistry] The resource registry to look up resources.
27
+ * @throws {MissingActionResource} If resource is absent or falsy.
28
+ */
29
+ constructor({
30
+ resource,
31
+ pagination,
32
+ jobRegistry = DefaultJobRegistry,
33
+ resourceRegistry = DefaultResourceRegistry,
34
+ }) {
35
+ if (!resource) throw new MissingActionResource();
36
+ this.#resource = resource;
37
+ this.#pagination = PaginationConfig.fromList(pagination);
38
+ this.#jobRegistry = jobRegistry;
39
+ this.#resourceRegistry = resourceRegistry;
40
+ }
41
+
42
+ /**
43
+ * Evaluates the page count from the response, then enqueues one
44
+ * ResourceRequestJob per page for the target resource.
45
+ * @param {ResponseWrapper} responseWrapper A ResponseWrapper instance exposing parsedBody and headers.
46
+ * @param {object} [parameters={}] The original request parameters to merge with the page number.
47
+ * @returns {void}
48
+ */
49
+ execute(responseWrapper, parameters = {}) {
50
+ if (Application.isStopped()) return;
51
+
52
+ const count = this.#pagination.resolvePages(responseWrapper);
53
+ const pages = this.#pagination.pageNumbers(count);
54
+ const resource = this.#resourceRegistry.getItem(this.#resource);
55
+
56
+ for (const page of pages) {
57
+ const pageParameters = { ...parameters, [this.#pagination.pageKey]: page };
58
+ for (const resourceRequest of resource.resourceRequests) {
59
+ this.#jobRegistry.enqueue('ResourceRequestJob', { resourceRequest, parameters: pageParameters });
60
+ }
61
+ }
62
+ }
63
+
64
+ /**
65
+ * Creates instances from a raw YAML list, skipping invalid entries.
66
+ * @param {Array<object>} [array=[]] Raw paginated action config entries.
67
+ * @returns {Array<ResourceRequestPaginatedAction>} Valid paginated action instances.
68
+ */
69
+ static fromList(array = []) {
70
+ return array.flatMap((attrs) => {
71
+ try {
72
+ return [new ResourceRequestPaginatedAction(attrs)];
73
+ } catch (error) {
74
+ LogRegistry.error(`Skipping paginated_action: ${error}`);
75
+ return [];
76
+ }
77
+ });
78
+ }
79
+ }
80
+
81
+ export { ResourceRequestPaginatedAction };
@@ -1,4 +1,4 @@
1
- import { MissingMappingVariable } from '../exceptions/MissingMappingVariable.js';
1
+ import { MissingMappingVariable } from '../../exceptions/registry/MissingMappingVariable.js';
2
2
 
3
3
  /**
4
4
  * Traverses an object one path segment at a time, throwing when
@@ -1,4 +1,4 @@
1
- import { InvalidResponseBody } from '../exceptions/InvalidResponseBody.js';
1
+ import { InvalidResponseBody } from '../../exceptions/request/InvalidResponseBody.js';
2
2
 
3
3
  /**
4
4
  * Parses a raw JSON response body string into a JavaScript value.
@@ -1,5 +1,5 @@
1
1
  import { NamedRegistry } from './NamedRegistry.js';
2
- import { ClientNotFound } from '../exceptions/ClientNotFound.js';
2
+ import { ClientNotFound } from '../exceptions/registry/ClientNotFound.js';
3
3
 
4
4
  /**
5
5
  * ClientRegistry manages client retrieval logic and exposes a static singleton facade.
@@ -54,8 +54,8 @@ class LogRegistry {
54
54
 
55
55
  /**
56
56
  * Gets a specific log by ID.
57
- * @param {number} id
58
- * @returns {import('../utils/logging/Log.js').Log|undefined}
57
+ * @param {number} id - The log entry ID to look up.
58
+ * @returns {import('../utils/logging/Log.js').Log|undefined} The matching log entry, or undefined if not found.
59
59
  */
60
60
  static getLogById(id) {
61
61
  return LogRegistry.#getInstance().getLogById(id);
@@ -63,10 +63,10 @@ class LogRegistry {
63
63
 
64
64
  /**
65
65
  * Gets logs in chronological order (oldest first), optionally filtered to entries newer than lastId.
66
- * @param {object} [options={}]
66
+ * @param {object} [options={}] - Query options.
67
67
  * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
68
68
  * Returns an empty array if the ID is not found.
69
- * @returns {Array<import('../utils/logging/Log.js').Log>}
69
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
70
70
  */
71
71
  static getLogs({ lastId } = {}) {
72
72
  return LogRegistry.#getInstance().getLogs({ lastId });
@@ -75,10 +75,10 @@ class LogRegistry {
75
75
  /**
76
76
  * Gets logs stored in the per-job buffer for the given job ID,
77
77
  * optionally filtered to entries newer than lastId.
78
- * @param {string|number} jobId
79
- * @param {object} [options={}]
78
+ * @param {string|number} jobId - The job ID to look up logs for.
79
+ * @param {object} [options={}] - Query options.
80
80
  * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
81
- * @returns {Array<import('../utils/logging/Log.js').Log>}
81
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
82
82
  */
83
83
  static getLogsByJobId(jobId, { lastId } = {}) {
84
84
  return LogRegistry.#getInstance().getLogsByJobId(jobId, { lastId });
@@ -86,8 +86,8 @@ class LogRegistry {
86
86
 
87
87
  /**
88
88
  * Gets logs stored in the per-worker buffer for the given worker ID.
89
- * @param {string|number} workerId
90
- * @returns {Array<import('../utils/logging/Log.js').Log>}
89
+ * @param {string|number} workerId - The worker ID to look up logs for.
90
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
91
91
  */
92
92
  static getLogsByWorkerId(workerId) {
93
93
  return LogRegistry.#getInstance().getLogsByWorkerId(workerId);
@@ -95,8 +95,8 @@ class LogRegistry {
95
95
 
96
96
  /**
97
97
  * Gets logs filtered by level.
98
- * @param {string} level
99
- * @returns {Array<import('../utils/logging/Log.js').Log>}
98
+ * @param {string} level - The log level to filter by.
99
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries matching the level.
100
100
  */
101
101
  static getLogsByLevel(level) {
102
102
  return LogRegistry.#getInstance().getLogsByLevel(level);
@@ -104,7 +104,7 @@ class LogRegistry {
104
104
 
105
105
  /**
106
106
  * Returns all logs as plain JSON objects.
107
- * @returns {Array<object>}
107
+ * @returns {Array<object>} Array of plain log objects.
108
108
  */
109
109
  static getLogsJSON() {
110
110
  return LogRegistry.#getInstance().getLogsJSON();
@@ -132,7 +132,7 @@ class LogRegistry {
132
132
 
133
133
  /**
134
134
  * Returns the singleton instance, throwing if not yet built.
135
- * @returns {LogRegistryInstance}
135
+ * @returns {LogRegistryInstance} The singleton instance.
136
136
  * @throws {Error} If build() has not been called.
137
137
  */
138
138
  static #getInstance() {
@@ -31,7 +31,7 @@ class LogRegistryInstance {
31
31
 
32
32
  /**
33
33
  * Returns the underlying BufferedLogger instance.
34
- * @returns {BufferedLogger}
34
+ * @returns {BufferedLogger} The underlying BufferedLogger instance.
35
35
  */
36
36
  get bufferedLogger() {
37
37
  return this.#bufferedLogger;
@@ -59,8 +59,8 @@ class LogRegistryInstance {
59
59
 
60
60
  /**
61
61
  * Gets a specific log by ID.
62
- * @param {number} id
63
- * @returns {import('../utils/logging/Log.js').Log|undefined}
62
+ * @param {number} id - The log entry ID to look up.
63
+ * @returns {import('../utils/logging/Log.js').Log|undefined} The matching log entry, or undefined if not found.
64
64
  */
65
65
  getLogById(id) {
66
66
  return this.#bufferedLogger.getLogById(id);
@@ -68,10 +68,10 @@ class LogRegistryInstance {
68
68
 
69
69
  /**
70
70
  * Gets logs in chronological order (oldest first), optionally filtered to entries newer than lastId.
71
- * @param {object} [options={}]
71
+ * @param {object} [options={}] - Query options.
72
72
  * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
73
73
  * Returns an empty array if the ID is not found.
74
- * @returns {Array<import('../utils/logging/Log.js').Log>}
74
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
75
75
  */
76
76
  getLogs({ lastId } = {}) {
77
77
  return new LogFilter(this.bufferedLogger.getLogs()).filter({ lastId });
@@ -80,10 +80,10 @@ class LogRegistryInstance {
80
80
  /**
81
81
  * Gets logs stored in the per-job buffer for the given job ID,
82
82
  * optionally filtered to entries newer than lastId.
83
- * @param {string|number} jobId
84
- * @param {object} [options={}]
83
+ * @param {string|number} jobId - The job ID to look up logs for.
84
+ * @param {object} [options={}] - Query options.
85
85
  * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
86
- * @returns {Array<import('../utils/logging/Log.js').Log>}
86
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
87
87
  */
88
88
  getLogsByJobId(jobId, { lastId } = {}) {
89
89
  return new LogFilter(this.#jobLogs.getLogs(jobId)).filter({ lastId });
@@ -91,8 +91,8 @@ class LogRegistryInstance {
91
91
 
92
92
  /**
93
93
  * Gets logs stored in the per-worker buffer for the given worker ID.
94
- * @param {string|number} workerId
95
- * @returns {Array<import('../utils/logging/Log.js').Log>}
94
+ * @param {string|number} workerId - The worker ID to look up logs for.
95
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries.
96
96
  */
97
97
  getLogsByWorkerId(workerId) {
98
98
  return this.#workerLogs.getLogs(workerId);
@@ -100,8 +100,8 @@ class LogRegistryInstance {
100
100
 
101
101
  /**
102
102
  * Gets logs filtered by level.
103
- * @param {string} level
104
- * @returns {Array<import('../utils/logging/Log.js').Log>}
103
+ * @param {string} level - The log level to filter by.
104
+ * @returns {Array<import('../utils/logging/Log.js').Log>} Array of log entries matching the level.
105
105
  */
106
106
  getLogsByLevel(level) {
107
107
  return this.#bufferedLogger.getLogsByLevel(level);
@@ -109,7 +109,7 @@ class LogRegistryInstance {
109
109
 
110
110
  /**
111
111
  * Returns all logs as plain JSON objects.
112
- * @returns {Array<object>}
112
+ * @returns {Array<object>} Array of plain log objects.
113
113
  */
114
114
  getLogsJSON() {
115
115
  return this.#bufferedLogger.getLogsJSON();
@@ -138,9 +138,9 @@ class LogRegistryInstance {
138
138
  /**
139
139
  * Fans out the log call to the logger group and, if a new log was buffered,
140
140
  * routes it to the per-job and per-worker collections based on attributes.
141
- * @param {string} level
142
- * @param {string} message
143
- * @param {object} attributes
141
+ * @param {string} level - The log level.
142
+ * @param {string} message - The log message.
143
+ * @param {object} attributes - Optional structured metadata.
144
144
  * @returns {void}
145
145
  */
146
146
  #dispatch(level, message, attributes) {
@@ -1,4 +1,4 @@
1
- import { ItemNotFound } from '../exceptions/ItemNotFound.js';
1
+ import { ItemNotFound } from '../exceptions/registry/ItemNotFound.js';
2
2
 
3
3
  /**
4
4
  * NamedRegistry is a base class for registries that manage named items.
@@ -1,5 +1,5 @@
1
1
  import { NamedRegistry } from './NamedRegistry.js';
2
- import { ResourceNotFound } from '../exceptions/ResourceNotFound.js';
2
+ import { ResourceNotFound } from '../exceptions/registry/ResourceNotFound.js';
3
3
 
4
4
  /**
5
5
  * Registry of named Resource instances.
@@ -8,6 +8,7 @@ class JobIndexSerializer extends Serializer {
8
8
  /**
9
9
  * Serializes a single job instance into a `{ id, status, attempts, jobClass[, url] }` object.
10
10
  * For `ResourceRequestJob` instances, the resolved URL is included as `url`.
11
+ * For other job instances that carry an `originUrl` argument, that value is included as `url`.
11
12
  *
12
13
  * @param {object} job - A job instance.
13
14
  * @param {object} options - Serialization options.
@@ -24,6 +25,8 @@ class JobIndexSerializer extends Serializer {
24
25
 
25
26
  if (job.constructor.name === 'ResourceRequestJob') {
26
27
  result.url = job.arguments?.url;
28
+ } else if (job.arguments?.originUrl) {
29
+ result.url = job.arguments.originUrl;
27
30
  }
28
31
 
29
32
  return result;
@@ -10,7 +10,7 @@ class LogSerializer extends Serializer {
10
10
  * Serializes a single Log instance.
11
11
  *
12
12
  * @param {import('../utils/logging/Log.js').Log} log - The log entry to serialize.
13
- * @returns {{ id: number, level: string, message: string, attributes: object, timestamp: string }}
13
+ * @returns {{ id: number, level: string, message: string, attributes: object, timestamp: string }} Plain object representation of the log entry.
14
14
  */
15
15
  static _serializeObject(log) {
16
16
  return {
@@ -1,5 +1,5 @@
1
1
  import path from 'path';
2
- import { ForbiddenError } from '../exceptions/ForbiddenError.js';
2
+ import { ForbiddenError } from '../exceptions/http/ForbiddenError.js';
3
3
 
4
4
  /**
5
5
  * Validates that a resolved file path stays within an allowed base directory,
@@ -1,6 +1,6 @@
1
- import { ConflictError } from '../exceptions/ConflictError.js';
2
- import { ForbiddenError } from '../exceptions/ForbiddenError.js';
3
- import { NotFoundError } from '../exceptions/NotFoundError.js';
1
+ import { ConflictError } from '../exceptions/http/ConflictError.js';
2
+ import { ForbiddenError } from '../exceptions/http/ForbiddenError.js';
3
+ import { NotFoundError } from '../exceptions/http/NotFoundError.js';
4
4
  import { Logger } from '../utils/logging/Logger.js';
5
5
 
6
6
  /**
@@ -1,24 +1,24 @@
1
1
  import path from 'path';
2
2
  import { fileURLToPath } from 'url';
3
3
  import express from 'express';
4
- import { AssetsRequestHandler } from './AssetsRequestHandler.js';
5
- import { BaseUrlsRequestHandler } from './BaseUrlsRequestHandler.js';
6
- import { EngineContinueRequestHandler } from './EngineContinueRequestHandler.js';
7
- import { EnginePauseRequestHandler } from './EnginePauseRequestHandler.js';
8
- import { EngineRestartRequestHandler } from './EngineRestartRequestHandler.js';
9
- import { EngineShutdownRequestHandler } from './EngineShutdownRequestHandler.js';
10
- import { EngineStartRequestHandler } from './EngineStartRequestHandler.js';
11
- import { EngineStatusRequestHandler } from './EngineStatusRequestHandler.js';
12
- import { EngineStopRequestHandler } from './EngineStopRequestHandler.js';
13
- import { IndexRequestHandler } from './IndexRequestHandler.js';
14
- import { JobLogsRequestHandler } from './JobLogsRequestHandler.js';
15
- import { JobRequestHandler } from './JobRequestHandler.js';
16
- import { JobRetryRequestHandler } from './JobRetryRequestHandler.js';
17
- import { JobsRequestHandler } from './JobsRequestHandler.js';
18
- import { LogsRequestHandler } from './LogsRequestHandler.js';
4
+ import { AssetsRequestHandler } from './handlers/AssetsRequestHandler.js';
5
+ import { BaseUrlsRequestHandler } from './handlers/BaseUrlsRequestHandler.js';
6
+ import { EngineContinueRequestHandler } from './handlers/engine/EngineContinueRequestHandler.js';
7
+ import { EnginePauseRequestHandler } from './handlers/engine/EnginePauseRequestHandler.js';
8
+ import { EngineRestartRequestHandler } from './handlers/engine/EngineRestartRequestHandler.js';
9
+ import { EngineShutdownRequestHandler } from './handlers/engine/EngineShutdownRequestHandler.js';
10
+ import { EngineStartRequestHandler } from './handlers/engine/EngineStartRequestHandler.js';
11
+ import { EngineStatusRequestHandler } from './handlers/engine/EngineStatusRequestHandler.js';
12
+ import { EngineStopRequestHandler } from './handlers/engine/EngineStopRequestHandler.js';
13
+ import { IndexRequestHandler } from './handlers/IndexRequestHandler.js';
14
+ import { JobLogsRequestHandler } from './handlers/jobs/JobLogsRequestHandler.js';
15
+ import { JobRequestHandler } from './handlers/jobs/JobRequestHandler.js';
16
+ import { JobRetryRequestHandler } from './handlers/jobs/JobRetryRequestHandler.js';
17
+ import { JobsRequestHandler } from './handlers/jobs/JobsRequestHandler.js';
18
+ import { LogsRequestHandler } from './handlers/LogsRequestHandler.js';
19
+ import { SettingsRequestHandler } from './handlers/SettingsRequestHandler.js';
20
+ import { StatsRequestHandler } from './handlers/StatsRequestHandler.js';
19
21
  import { RouteRegister } from './RouteRegister.js';
20
- import { SettingsRequestHandler } from './SettingsRequestHandler.js';
21
- import { StatsRequestHandler } from './StatsRequestHandler.js';
22
22
 
23
23
  const { Router: ExpressRouter } = express;
24
24
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -33,7 +33,7 @@ class Router {
33
33
 
34
34
  /**
35
35
  * Creates a new Router instance.
36
- * @param {object} [options={}]
36
+ * @param {object} [options={}] - Constructor options.
37
37
  * @param {object} [options.webConfig={}] - Web configuration, used by handlers that need it.
38
38
  */
39
39
  constructor({ webConfig = {} } = {}) {
@@ -1,7 +1,7 @@
1
1
  import path from 'path';
2
2
  import { fileURLToPath } from 'url';
3
- import { PathValidator } from './PathValidator.js';
4
- import { RequestHandler } from './RequestHandler.js';
3
+ import { PathValidator } from '../PathValidator.js';
4
+ import { RequestHandler } from '../RequestHandler.js';
5
5
 
6
6
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
7
7
 
@@ -16,7 +16,7 @@ class AssetsRequestHandler extends RequestHandler {
16
16
  */
17
17
  constructor() {
18
18
  super();
19
- this.assetsDir = path.resolve(__dirname, '../../static/assets');
19
+ this.assetsDir = path.resolve(__dirname, '../../../static/assets');
20
20
  this.validator = new PathValidator(this.assetsDir);
21
21
  }
22
22
 
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ClientRegistry } from '../registry/ClientRegistry.js';
3
- import { BaseUrlsSerializer } from '../serializers/BaseUrlsSerializer.js';
1
+ import { ClientRegistry } from '../../registry/ClientRegistry.js';
2
+ import { BaseUrlsSerializer } from '../../serializers/BaseUrlsSerializer.js';
3
+ import { RequestHandler } from '../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles GET /clients/base_urls.json requests.
@@ -1,9 +1,9 @@
1
1
  import path from 'path';
2
2
  import { fileURLToPath } from 'url';
3
- import { RequestHandler } from './RequestHandler.js';
3
+ import { RequestHandler } from '../RequestHandler.js';
4
4
 
5
5
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
6
- const staticDir = path.resolve(__dirname, '../../static');
6
+ const staticDir = path.resolve(__dirname, '../../../static');
7
7
 
8
8
  /**
9
9
  * Handles GET / and SPA catch-all requests by serving index.html.
@@ -32,7 +32,7 @@ class JobsFilter {
32
32
  * Returns true when the job's class is listed in the requested classes.
33
33
  * @param {object} job - A job instance.
34
34
  * @param {string[]} classes - The list of accepted class names.
35
- * @returns {boolean}
35
+ * @returns {boolean} True if the job's class is in the accepted list.
36
36
  */
37
37
  #matchesClass(job, classes) {
38
38
  return classes.includes(job.constructor.name);
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { LogRegistry } from '../registry/LogRegistry.js';
3
- import { LogSerializer } from '../serializers/LogSerializer.js';
1
+ import { LogRegistry } from '../../registry/LogRegistry.js';
2
+ import { LogSerializer } from '../../serializers/LogSerializer.js';
3
+ import { RequestHandler } from '../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles GET /logs.json requests.
@@ -13,7 +13,7 @@ class LogsRequestHandler extends RequestHandler {
13
13
 
14
14
  /**
15
15
  * Creates a new LogsRequestHandler.
16
- * @param {object} [options={}]
16
+ * @param {object} [options={}] - Constructor options.
17
17
  * @param {number} [options.pageSize=20] - Maximum number of log entries to return.
18
18
  */
19
19
  constructor({ pageSize = 20 } = {}) {
@@ -1,5 +1,5 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ForbiddenError } from '../exceptions/ForbiddenError.js';
1
+ import { ForbiddenError } from '../../exceptions/http/ForbiddenError.js';
2
+ import { RequestHandler } from '../RequestHandler.js';
3
3
 
4
4
  /**
5
5
  * Handles GET /settings.json requests.
@@ -11,7 +11,8 @@ class SettingsRequestHandler extends RequestHandler {
11
11
  #enableShutdown;
12
12
 
13
13
  /**
14
- * @param {object} [options={}]
14
+ * Creates a new SettingsRequestHandler.
15
+ * @param {object} [options={}] - Constructor options.
15
16
  * @param {boolean} [options.enableShutdown=true] - Whether shutdown is permitted.
16
17
  */
17
18
  constructor({ enableShutdown = true } = {}) {
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { JobRegistry } from '../background/JobRegistry.js';
3
- import { WorkersRegistry } from '../background/WorkersRegistry.js';
1
+ import { JobRegistry } from '../../background/JobRegistry.js';
2
+ import { WorkersRegistry } from '../../background/WorkersRegistry.js';
3
+ import { RequestHandler } from '../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles GET /stats.json requests.
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ConflictError } from '../exceptions/ConflictError.js';
3
- import { Application } from '../services/Application.js';
1
+ import { ConflictError } from '../../../exceptions/http/ConflictError.js';
2
+ import { Application } from '../../../services/Application.js';
3
+ import { RequestHandler } from '../../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles PATCH /engine/continue requests.
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ConflictError } from '../exceptions/ConflictError.js';
3
- import { Application } from '../services/Application.js';
1
+ import { ConflictError } from '../../../exceptions/http/ConflictError.js';
2
+ import { Application } from '../../../services/Application.js';
3
+ import { RequestHandler } from '../../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles PATCH /engine/pause requests.
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ConflictError } from '../exceptions/ConflictError.js';
3
- import { Application } from '../services/Application.js';
1
+ import { ConflictError } from '../../../exceptions/http/ConflictError.js';
2
+ import { Application } from '../../../services/Application.js';
3
+ import { RequestHandler } from '../../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles PATCH /engine/restart requests.
@@ -1,5 +1,5 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { Application } from '../services/Application.js';
1
+ import { Application } from '../../../services/Application.js';
2
+ import { RequestHandler } from '../../RequestHandler.js';
3
3
 
4
4
  /**
5
5
  * Handles PATCH /engine/shutdown requests.
@@ -1,6 +1,6 @@
1
- import { RequestHandler } from './RequestHandler.js';
2
- import { ConflictError } from '../exceptions/ConflictError.js';
3
- import { Application } from '../services/Application.js';
1
+ import { ConflictError } from '../../../exceptions/http/ConflictError.js';
2
+ import { Application } from '../../../services/Application.js';
3
+ import { RequestHandler } from '../../RequestHandler.js';
4
4
 
5
5
  /**
6
6
  * Handles PATCH /engine/start requests.