@rapidrest/service-core 1.0.0-beta.1 → 1.0.0-beta.2

package/docs/reference/classes/HttpRouter.md

@@ -0,0 +1,343 @@
+[**@rapidrest/service-core**](../README.md)
+
+***
+
+[@rapidrest/service-core](../globals.md) / HttpRouter
+
+# Class: HttpRouter
+
+Defined in: [src/http/Router.ts:214](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L214)
+
+Thin Express-compatible wrapper over `uWS.TemplatedApp`.
+
+Provides the same `app.get()`, `app.post()`, `app.use()`, etc. API that
+`RouteUtils.registerRoute()` uses, so no changes are needed in route registration
+code. Global middleware registered via `use()` is prepended to every route's chain.
+
+Also supports:
+- `ws(path, handlers)` — native uWS WebSocket routing
+- `static(basePath)` — basic static file serving
+- `listen(host, port)` / `close()` — server lifecycle
+
+## Indexable
+
+> \[`key`: `string`\]: `any`
+
+## Constructors
+
+### Constructor
+
+> **new HttpRouter**(`uwsApp`): `HttpRouter`
+
+Defined in: [src/http/Router.ts:226](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L226)
+
+#### Parameters
+
+##### uwsApp
+
+`TemplatedApp`
+
+#### Returns
+
+`HttpRouter`
+
+## Properties
+
+### listenPort
+
+> **listenPort**: `number` = `0`
+
+Defined in: [src/http/Router.ts:224](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L224)
+
+The port the server is currently listening on (set after a successful `listen()` call).
+
+## Accessors
+
+### isListening
+
+#### Get Signature
+
+> **get** **isListening**(): `boolean`
+
+Defined in: [src/http/Router.ts:231](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L231)
+
+Returns `true` if the server is currently listening.
+
+##### Returns
+
+`boolean`
+
+## Methods
+
+### close()
+
+> **close**(): `void`
+
+Defined in: [src/http/Router.ts:471](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L471)
+
+Closes the listen socket, stopping the server from accepting new connections.
+
+#### Returns
+
+`void`
+
+***
+
+### delete()
+
+> **delete**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:275](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L275)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### get()
+
+> **get**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:257](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L257)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### head()
+
+> **head**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:287](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L287)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### listen()
+
+> **listen**(`host`, `port`): `Promise`\<`void`\>
+
+Defined in: [src/http/Router.ts:450](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L450)
+
+Starts listening on the given host and port.
+Resolves when the server is ready; rejects if the port cannot be bound.
+
+#### Parameters
+
+##### host
+
+`string`
+
+##### port
+
+`number`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### options()
+
+> **options**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:294](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L294)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### patch()
+
+> **patch**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:281](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L281)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### post()
+
+> **post**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:263](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L263)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### put()
+
+> **put**(`routePath`, ...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:269](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L269)
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### static()
+
+> **static**(`basePath`): `this`
+
+Defined in: [src/http/Router.ts:420](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L420)
+
+Serves static files from a directory via a wildcard GET route.
+Files not found on disk return 404.
+
+#### Parameters
+
+##### basePath
+
+`string`
+
+#### Returns
+
+`this`
+
+***
+
+### use()
+
+> **use**(...`handlers`): `this`
+
+Defined in: [src/http/Router.ts:236](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L236)
+
+Register global middleware that runs before every route handler.
+
+#### Parameters
+
+##### handlers
+
+...[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+#### Returns
+
+`this`
+
+***
+
+### ws()
+
+> **ws**(`routePath`, `handlers`, `wsOptions?`, `upgradeAuth?`): `this`
+
+Defined in: [src/http/Router.ts:312](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/http/Router.ts#L312)
+
+Registers a WebSocket route. Handlers follow the same `(req, res, next)` pattern
+as HTTP routes; they receive `req.websocket` containing the uWS WebSocket handle.
+
+`upgradeAuth` is an optional pre-upgrade auth function. When provided it runs synchronously
+inside the uWS `upgrade` callback before the handshake. If it returns `{ reject: true }`,
+an HTTP 401 is sent and the upgrade is aborted. If it returns `{ user, ... }`, those
+credentials are attached to the request so downstream middleware sees an authenticated user.
+If it returns `{}`, auth falls through to the post-upgrade message-based LOGIN flow.
+
+Both `path` and `path + "/"` are registered to avoid trailing-slash mismatch.
+
+#### Parameters
+
+##### routePath
+
+`string`
+
+##### handlers
+
+[`RequestHandler`](../type-aliases/RequestHandler.md)[]
+
+##### wsOptions?
+
+`Partial`\<`WebSocketBehavior`\<`any`\>\>
+
+##### upgradeAuth?
+
+[`WsUpgradeAuth`](../type-aliases/WsUpgradeAuth.md)
+
+#### Returns
+
+`this`

package/docs/reference/classes/JWTStrategy.md

@@ -6,15 +6,15 @@
 
 # Class: JWTStrategy
 
-Defined in: [src/auth/JWTStrategy.ts:64](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L64)
+Defined in: [src/auth/JWTStrategy.ts:63](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L63)
 
-JWT authentication strategy. Performs JWT verification and searches for a token by one of the
-following methods (in order of precedence):
-* Query Parameter
-* Authorization Header
+JWT authentication strategy. Performs JWT verification and searches for a token by one of the
+following methods (in order of precedence):
+* Query Parameter
+* Authorization Header
 * Cookie
 
-This class no longer extends `passport-strategy`; it is used directly by route middleware
+This class no longer extends `passport-strategy`; it is used directly by route middleware
 and returns a plain result object instead of calling Passport callbacks.
 
 ## Author
@@ -27,7 +27,7 @@ Jean-Philippe Steinmetz
 
 > **new JWTStrategy**(`options?`): `JWTStrategy`
 
-Defined in: [src/auth/JWTStrategy.ts:72](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L72)
+Defined in: [src/auth/JWTStrategy.ts:71](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L71)
 
 #### Parameters
 
@@ -45,28 +45,51 @@ Defined in: [src/auth/JWTStrategy.ts:72](https://github.com/rapidrest/service-co
 
 > `readonly` **name**: `string` = `"jwt"`
 
-Defined in: [src/auth/JWTStrategy.ts:68](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L68)
+Defined in: [src/auth/JWTStrategy.ts:67](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L67)
 
 ## Methods
 
 ### authenticate()
 
-> **authenticate**(`req`, `res`, `required?`): [`JWTAuthResult`](../interfaces/JWTAuthResult.md) \| `undefined`
+> **authenticate**(`req`, `res`, `required?`): `Promise`\<[`JWTAuthResult`](../interfaces/JWTAuthResult.md) \| `undefined`\>
 
-Defined in: [src/auth/JWTStrategy.ts:81](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L81)
+Defined in: [src/auth/JWTStrategy.ts:134](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L134)
 
-Attempts to authenticate the incoming request by extracting and verifying a JWT token.
-Returns a `JWTAuthResult` describing the outcome.
+#### Parameters
+
+##### req
+
+[`HttpRequest`](../interfaces/HttpRequest.md)
+
+##### res
+
+[`HttpResponse`](../interfaces/HttpResponse.md)
+
+##### required?
+
+`boolean`
+
+#### Returns
+
+`Promise`\<[`JWTAuthResult`](../interfaces/JWTAuthResult.md) \| `undefined`\>
+
+***
+
+### authenticateSync()
+
+> **authenticateSync**(`req`, `res`, `required?`): [`JWTAuthResult`](../interfaces/JWTAuthResult.md) \| `undefined`
+
+Defined in: [src/auth/JWTStrategy.ts:169](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L169)
 
 #### Parameters
 
 ##### req
 
-`HttpRequest`
+[`HttpRequest`](../interfaces/HttpRequest.md)
 
 ##### res
 
-`HttpResponse`
+[`HttpResponse`](../interfaces/HttpResponse.md)
 
 ##### required?
 

package/docs/reference/classes/JWTStrategyOptions.md

@@ -6,7 +6,7 @@
 
 # Class: JWTStrategyOptions
 
-Defined in: [src/auth/JWTStrategy.ts:20](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L20)
+Defined in: [src/auth/JWTStrategy.ts:19](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L19)
 
 Describes the configuration options that can be used to initialize JWTStrategy.
 
@@ -30,10 +30,10 @@ Jean-Philippe Steinmetz
 
 > **allowQueryParam**: `boolean` = `false`
 
-Defined in: [src/auth/JWTStrategy.ts:38](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L38)
+Defined in: [src/auth/JWTStrategy.ts:37](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L37)
 
-Set to `true` to allow tokens to be supplied via the `queryKey` URL parameter.
-Disabled by default — query parameters appear in server logs, browser history, and
+Set to `true` to allow tokens to be supplied via the `queryKey` URL parameter.
+Disabled by default — query parameters appear in server logs, browser history, and
 Referer headers, which permanently exposes tokens outside the application.
 
 ***
@@ -42,7 +42,7 @@ Referer headers, which permanently exposes tokens outside the application.
 
 > `optional` **config?**: `JWTUtilsConfig`
 
-Defined in: [src/auth/JWTStrategy.ts:22](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L22)
+Defined in: [src/auth/JWTStrategy.ts:21](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L21)
 
 The configuration options to pass to the JWTUtils library during token verification.
 
@@ -52,7 +52,7 @@ The configuration options to pass to the JWTUtils library during token verificat
 
 > **cookieName**: `string` = `"jwt"`
 
-Defined in: [src/auth/JWTStrategy.ts:28](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L28)
+Defined in: [src/auth/JWTStrategy.ts:27](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L27)
 
 The name of the cookie to retrieve the token from when using cookie based authentication. Default value is `jwt`.
 
@@ -62,7 +62,7 @@ The name of the cookie to retrieve the token from when using cookie based authen
 
 > **cookieSecure**: `boolean` = `false`
 
-Defined in: [src/auth/JWTStrategy.ts:30](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L30)
+Defined in: [src/auth/JWTStrategy.ts:29](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L29)
 
 The name of the secured cookie to retreive the token from when using cookie based authentication.
 
@@ -72,7 +72,7 @@ The name of the secured cookie to retreive the token from when using cookie base
 
 > **headerKey**: `string` = `"authorization"`
 
-Defined in: [src/auth/JWTStrategy.ts:24](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L24)
+Defined in: [src/auth/JWTStrategy.ts:23](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L23)
 
 The name of the header to look for when performing header based authentication. Default value is `Authorization`.
 
@@ -82,7 +82,7 @@ The name of the header to look for when performing header based authentication.
 
 > **headerScheme**: `string` = "(jwt\|bearer)"
 
-Defined in: [src/auth/JWTStrategy.ts:26](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L26)
+Defined in: [src/auth/JWTStrategy.ts:25](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L25)
 
 The authorization scheme type when using header based authentication. Default value is `jwt`.
 
@@ -92,6 +92,6 @@ The authorization scheme type when using header based authentication. Default va
 
 > **queryKey**: `string` = `"auth_token"`
 
-Defined in: [src/auth/JWTStrategy.ts:32](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/auth/JWTStrategy.ts#L32)
+Defined in: [src/auth/JWTStrategy.ts:31](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/auth/JWTStrategy.ts#L31)
 
 The name of the request query parameter to retrieve the token from when using query based authentication. Default value is `auth_token`.

package/docs/reference/classes/MetricsRoute.md

@@ -6,7 +6,7 @@
 
 # Class: MetricsRoute
 
-Defined in: [src/routes/MetricsRoute.ts:19](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/routes/MetricsRoute.ts#L19)
+Defined in: [src/routes/MetricsRoute.ts:19](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/routes/MetricsRoute.ts#L19)
 
 Handles all REST API requests for the endpoint `/metrics'. This route handler produces Prometheus compatible metrics
 for use with a Prometheus based server.
@@ -20,7 +20,7 @@ from the provided `prom-client` dependency. See the `prom-client` documentation
 
 > **new MetricsRoute**(): `MetricsRoute`
 
-Defined in: [src/routes/MetricsRoute.ts:30](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/routes/MetricsRoute.ts#L30)
+Defined in: [src/routes/MetricsRoute.ts:30](https://github.com/rapidrest/service-core/blob/5cd5bc79b3569101eabf54dec613fd4745a69b2b/src/routes/MetricsRoute.ts#L30)
 
 #### Returns