@ovineko/spa-guard-fastify 0.0.1-alpha-25 → 0.0.1-alpha-26
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.
- package/README.md +100 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# @ovineko/spa-guard-fastify
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ovineko/spa-guard-fastify)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
|
|
6
|
+
Fastify plugin for spa-guard beacon endpoint and HTML cache handler with ETag/304 support.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
npm install @ovineko/spa-guard-fastify @ovineko/spa-guard-node fastify fastify-plugin
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
### Beacon endpoint
|
|
17
|
+
|
|
18
|
+
Register the plugin to receive beacon data posted by the spa-guard client runtime:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import Fastify from "fastify";
|
|
22
|
+
import { fastifySPAGuard } from "@ovineko/spa-guard-fastify";
|
|
23
|
+
|
|
24
|
+
const app = Fastify();
|
|
25
|
+
|
|
26
|
+
app.addContentTypeParser("text/plain", { parseAs: "string" }, (_req, body, done) => {
|
|
27
|
+
done(null, body);
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
app.register(fastifySPAGuard, {
|
|
31
|
+
path: "/api/beacon",
|
|
32
|
+
onBeacon: async (beacon, request, reply) => {
|
|
33
|
+
request.log.info({ beacon }, "SPA Guard beacon received");
|
|
34
|
+
// optionally suppress default log
|
|
35
|
+
return { skipDefaultLog: true };
|
|
36
|
+
},
|
|
37
|
+
onUnknownBeacon: async (body, request) => {
|
|
38
|
+
request.log.warn({ body }, "Unknown beacon format");
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
await app.listen({ port: 3000 });
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### HTML cache handler
|
|
46
|
+
|
|
47
|
+
Serve your SPA's `index.html` with ETag/304 and compression negotiation:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { createReadStream } from "node:fs";
|
|
51
|
+
import { spaGuardFastifyHandler } from "@ovineko/spa-guard-fastify";
|
|
52
|
+
import { createHtmlCache } from "@ovineko/spa-guard-node";
|
|
53
|
+
|
|
54
|
+
const handlerOptions = {};
|
|
55
|
+
|
|
56
|
+
app.get("/*", async (request, reply) => {
|
|
57
|
+
return spaGuardFastifyHandler(request, reply, {
|
|
58
|
+
...handlerOptions,
|
|
59
|
+
getHtml: () => ({ html: "<html>...</html>" }),
|
|
60
|
+
});
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## API
|
|
65
|
+
|
|
66
|
+
### `fastifySPAGuard` (Fastify plugin)
|
|
67
|
+
|
|
68
|
+
Registers a `POST` route at `options.path` to receive beacon payloads.
|
|
69
|
+
|
|
70
|
+
Options:
|
|
71
|
+
|
|
72
|
+
- `path` (required) - Route path for the beacon endpoint, e.g. `"/api/beacon"`
|
|
73
|
+
- `onBeacon(beacon, request, reply)` - Called with parsed beacon data. Return `{ skipDefaultLog: true }` to suppress default logging.
|
|
74
|
+
- `onUnknownBeacon(body, request, reply)` - Called when beacon fails schema validation. Return `{ skipDefaultLog: true }` to suppress default warning.
|
|
75
|
+
|
|
76
|
+
### `spaGuardFastifyHandler(request, reply, options)`
|
|
77
|
+
|
|
78
|
+
Fastify request handler that serves HTML with ETag/304 and content-encoding negotiation.
|
|
79
|
+
|
|
80
|
+
Options:
|
|
81
|
+
|
|
82
|
+
- `cache` - Pre-built `HtmlCache` instance
|
|
83
|
+
- `getHtml()` - Async factory returning `CreateHtmlCacheOptions`; cache is created lazily on first request
|
|
84
|
+
|
|
85
|
+
### Exported types
|
|
86
|
+
|
|
87
|
+
- `FastifySPAGuardOptions`
|
|
88
|
+
- `SpaGuardHandlerOptions`
|
|
89
|
+
- `BeaconHandlerResult`
|
|
90
|
+
- `BeaconError`
|
|
91
|
+
|
|
92
|
+
## Related packages
|
|
93
|
+
|
|
94
|
+
- [@ovineko/spa-guard](../spa-guard/README.md) - Core package
|
|
95
|
+
- [@ovineko/spa-guard-node](../node/README.md) - Node.js HTML cache
|
|
96
|
+
- [@ovineko/spa-guard-vite](../vite/README.md) - Vite build plugin
|
|
97
|
+
|
|
98
|
+
## License
|
|
99
|
+
|
|
100
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ovineko/spa-guard-fastify",
|
|
3
|
-
"version": "0.0.1-alpha-
|
|
3
|
+
"version": "0.0.1-alpha-26",
|
|
4
4
|
"description": "Fastify plugin for spa-guard beacon endpoint and HTML cache handler with ETag/304",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"spa",
|
|
@@ -34,12 +34,12 @@
|
|
|
34
34
|
"dist"
|
|
35
35
|
],
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@ovineko/spa-guard": "0.0.1-alpha-
|
|
37
|
+
"@ovineko/spa-guard": "0.0.1-alpha-26"
|
|
38
38
|
},
|
|
39
39
|
"peerDependencies": {
|
|
40
40
|
"fastify": "^5 || ^4",
|
|
41
41
|
"fastify-plugin": "^5 || ^4",
|
|
42
|
-
"@ovineko/spa-guard-node": "0.0.1-alpha-
|
|
42
|
+
"@ovineko/spa-guard-node": "0.0.1-alpha-26"
|
|
43
43
|
},
|
|
44
44
|
"engines": {
|
|
45
45
|
"node": ">=22.15.0"
|