ssrwire 0.1.0 → 0.3.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.
- package/CHANGELOG.md +45 -1
- package/CONTRIBUTING.md +8 -5
- package/PUBLISHING.md +92 -78
- package/README.md +117 -28
- package/SECURITY.md +8 -4
- package/dist/analyze.d.ts.map +1 -1
- package/dist/analyze.js +162 -6
- package/dist/analyze.js.map +1 -1
- package/dist/audit.d.ts.map +1 -1
- package/dist/audit.js +82 -7
- package/dist/audit.js.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +6 -1
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts +1 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +11 -0
- package/dist/config.js.map +1 -1
- package/dist/http-probe.d.ts.map +1 -1
- package/dist/http-probe.js +4 -0
- package/dist/http-probe.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/redact.d.ts.map +1 -1
- package/dist/redact.js +17 -0
- package/dist/redact.js.map +1 -1
- package/dist/reporters.d.ts.map +1 -1
- package/dist/reporters.js +69 -2
- package/dist/reporters.js.map +1 -1
- package/dist/social.d.ts +14 -0
- package/dist/social.d.ts.map +1 -0
- package/dist/social.js +88 -0
- package/dist/social.js.map +1 -0
- package/dist/stability.d.ts +9 -0
- package/dist/stability.d.ts.map +1 -0
- package/dist/stability.js +326 -0
- package/dist/stability.js.map +1 -0
- package/dist/stream-parser.d.ts.map +1 -1
- package/dist/stream-parser.js +21 -1
- package/dist/stream-parser.js.map +1 -1
- package/dist/types.d.ts +47 -0
- package/dist/types.d.ts.map +1 -1
- package/examples/github-actions.yml +2 -2
- package/examples/ssrwire.config.yml +8 -0
- package/package.json +5 -2
- package/src/analyze.ts +208 -7
- package/src/audit.ts +116 -8
- package/src/cli.ts +7 -1
- package/src/config.ts +12 -0
- package/src/http-probe.ts +4 -0
- package/src/index.ts +6 -0
- package/src/redact.ts +17 -0
- package/src/reporters.ts +97 -2
- package/src/social.ts +116 -0
- package/src/stability.ts +475 -0
- package/src/stream-parser.ts +31 -1
- package/src/types.ts +62 -0
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,48 @@ All notable changes to SSRWire are documented here. The project follows
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.3.0] - 2026-08-28
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Streamed capture for core Open Graph and Twitter Card metadata with arrival
|
|
13
|
+
time, observed byte position, document location, bounded repeated values, and
|
|
14
|
+
report redaction.
|
|
15
|
+
- Opt-in `require.openGraph` and `require.twitterCard` target contracts with
|
|
16
|
+
missing-field, invalid-URL, duplicate/conflict, and head/body delivery
|
|
17
|
+
findings.
|
|
18
|
+
- A terminal social-preview readiness table and public social metadata signal
|
|
19
|
+
types in JSON and the programmatic API.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- Enabled social contracts now participate in required-signal timing,
|
|
24
|
+
cross-agent comparison, and repeated-sample stability analysis.
|
|
25
|
+
- Twitter Card readiness prefers native Twitter metadata and falls back to the
|
|
26
|
+
corresponding Open Graph title, description, and image.
|
|
27
|
+
- Multiple `og:image` values are retained in document order without being
|
|
28
|
+
treated as conflicting scalar metadata.
|
|
29
|
+
|
|
30
|
+
## [0.2.0] - 2026-08-24
|
|
31
|
+
|
|
32
|
+
### Added
|
|
33
|
+
|
|
34
|
+
- Bounded `repeat` configuration and `--repeat` CLI sampling for 1–10 requests
|
|
35
|
+
per target-agent pair.
|
|
36
|
+
- Per-agent minimum, median, nearest-rank p95, maximum, and spread summaries for
|
|
37
|
+
response-header, first-byte, required-signal, and completion timings.
|
|
38
|
+
- Response and streamed-HTML stability findings across repeated samples.
|
|
39
|
+
- Sample attribution in terminal and JSON reports.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
|
|
43
|
+
- Added an npm package badge to the README.
|
|
44
|
+
- Samples for one target-agent pair run sequentially while independent pairs
|
|
45
|
+
retain bounded concurrency.
|
|
46
|
+
- Repeated policy findings are coalesced with occurrence and sample evidence.
|
|
47
|
+
- Exact body-fingerprint variation alone is informational; timing variation
|
|
48
|
+
alone remains evidence rather than a policy failure.
|
|
49
|
+
|
|
8
50
|
## [0.1.0] - 2026-08-22
|
|
9
51
|
|
|
10
52
|
### Added
|
|
@@ -16,5 +58,7 @@ All notable changes to SSRWire are documented here. The project follows
|
|
|
16
58
|
- Terminal, JSON, and SARIF reports with CI-safe exit codes.
|
|
17
59
|
- YAML configuration, one-off URL checks, Docker support, and GitHub Actions examples.
|
|
18
60
|
|
|
19
|
-
[Unreleased]: https://github.com/lame13/ssrwire/compare/v0.
|
|
61
|
+
[Unreleased]: https://github.com/lame13/ssrwire/compare/v0.3.0...HEAD
|
|
62
|
+
[0.3.0]: https://github.com/lame13/ssrwire/compare/v0.2.0...v0.3.0
|
|
63
|
+
[0.2.0]: https://github.com/lame13/ssrwire/compare/v0.1.0...v0.2.0
|
|
20
64
|
[0.1.0]: https://github.com/lame13/ssrwire/releases/tag/v0.1.0
|
package/CONTRIBUTING.md
CHANGED
|
@@ -28,7 +28,9 @@ Keep each change narrow. Include tests for behavior changes, especially for:
|
|
|
28
28
|
- response chunk boundaries and elements split across chunks;
|
|
29
29
|
- redirects, timeouts, aborted bodies, and size limits;
|
|
30
30
|
- malformed, duplicated, late, or body-located metadata;
|
|
31
|
+
- Open Graph and Twitter Card requirements, fallbacks, arrays, and URL values;
|
|
31
32
|
- user-agent differences and comparison findings;
|
|
33
|
+
- repeated-sample ordering, aggregation, and instability classification;
|
|
32
34
|
- redaction of configured header values;
|
|
33
35
|
- terminal, JSON, SARIF, and exit-code behavior.
|
|
34
36
|
|
|
@@ -39,11 +41,12 @@ positions instead.
|
|
|
39
41
|
|
|
40
42
|
## Scope
|
|
41
43
|
|
|
42
|
-
SSRWire is an HTTP stream observer
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
buffering can coalesce data
|
|
44
|
+
SSRWire is an HTTP stream observer and bounded consistency sampler, not a
|
|
45
|
+
browser, crawler, packet capture, load generator, performance benchmark, or
|
|
46
|
+
framework plugin. New features should preserve that boundary. In particular,
|
|
47
|
+
avoid conclusions that claim to reveal the server's original flush calls:
|
|
48
|
+
proxies, compression, TLS, HTTP stacks, and client buffering can coalesce data
|
|
49
|
+
before SSRWire sees it.
|
|
47
50
|
|
|
48
51
|
By contributing, you agree that your contribution is licensed under the MIT
|
|
49
52
|
License.
|
package/PUBLISHING.md
CHANGED
|
@@ -1,109 +1,124 @@
|
|
|
1
|
-
# Publish SSRWire from a local machine
|
|
1
|
+
# Publish SSRWire 0.3.0 from a local machine
|
|
2
2
|
|
|
3
|
-
This repository intentionally includes no npm publishing workflow.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
release
|
|
3
|
+
This repository intentionally includes no npm publishing workflow. Publish from
|
|
4
|
+
a foreground local terminal only after the GitHub `CI` workflow passes. Do not
|
|
5
|
+
configure an `NPM_TOKEN`, trusted publisher, OIDC identity, or automated npm
|
|
6
|
+
release job.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The `main` branch is protected. Land every release change through a pull
|
|
9
|
+
request, and do not use an administrator bypass or a direct push to `main`.
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
## 1. Update the existing repository
|
|
12
|
+
|
|
13
|
+
Work from a clean clone of the existing public repository. Copy the 0.3.0
|
|
14
|
+
source files into that clone while preserving its `.git` directory.
|
|
11
15
|
|
|
12
16
|
```bash
|
|
13
|
-
unzip ssrwire.zip # skip when already inside a source checkout
|
|
14
17
|
cd ssrwire
|
|
18
|
+
git switch main
|
|
19
|
+
git pull --ff-only origin main
|
|
20
|
+
git status --short
|
|
21
|
+
git switch -c release/0.3.0
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`git status --short` must be empty before creating the release branch and
|
|
25
|
+
applying the release files.
|
|
26
|
+
|
|
27
|
+
## 2. Verify the release locally
|
|
28
|
+
|
|
29
|
+
```bash
|
|
15
30
|
nvm use 24
|
|
16
31
|
node --version
|
|
17
32
|
npm --version
|
|
18
33
|
npm ci
|
|
19
34
|
npm run check
|
|
20
35
|
npm pack --dry-run
|
|
36
|
+
node dist/bin.js --version
|
|
21
37
|
```
|
|
22
38
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
brew install gh
|
|
27
|
-
gh auth login -h github.com --web
|
|
28
|
-
gh auth status -h github.com
|
|
29
|
-
```
|
|
39
|
+
The final command must print `0.3.0`. Inspect the dry-run file list. It must not
|
|
40
|
+
contain `.env`, `.github`, `node_modules`, `test`, ZIP files, or tarballs.
|
|
30
41
|
|
|
31
|
-
|
|
42
|
+
Review the release diff and version references:
|
|
32
43
|
|
|
33
44
|
```bash
|
|
34
|
-
git
|
|
35
|
-
git
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
biome.json examples package.json package-lock.json scripts src test \
|
|
39
|
-
tsconfig.build.json tsconfig.json vitest.config.ts
|
|
40
|
-
git commit -m "Initial SSRWire release"
|
|
45
|
+
git diff --check
|
|
46
|
+
git diff --stat
|
|
47
|
+
git diff -- package.json package-lock.json CHANGELOG.md README.md PUBLISHING.md
|
|
48
|
+
rg '0\.2\.0' README.md examples package.json package-lock.json scripts src test
|
|
41
49
|
```
|
|
42
50
|
|
|
43
|
-
|
|
51
|
+
The final search should return nothing. Historical entries in `CHANGELOG.md`
|
|
52
|
+
are excluded intentionally.
|
|
53
|
+
|
|
54
|
+
## 3. Commit, push the release branch, and open a pull request
|
|
44
55
|
|
|
45
56
|
```bash
|
|
46
|
-
gh
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
57
|
+
gh auth status -h github.com || gh auth login -h github.com --web
|
|
58
|
+
git add --all
|
|
59
|
+
git diff --cached --check
|
|
60
|
+
git diff --cached --stat
|
|
61
|
+
git commit -m "feat: release SSRWire 0.3.0"
|
|
62
|
+
git push --set-upstream origin release/0.3.0
|
|
63
|
+
gh pr create --base main --head release/0.3.0 --fill
|
|
64
|
+
PR_NUMBER="$(gh pr view release/0.3.0 --json number --jq .number)"
|
|
65
|
+
test -n "$PR_NUMBER"
|
|
66
|
+
gh pr checks "$PR_NUMBER" --watch --fail-fast
|
|
53
67
|
```
|
|
54
68
|
|
|
55
|
-
|
|
69
|
+
Do not merge while any Node, package-smoke, or Docker job is failing. Satisfy
|
|
70
|
+
all review and branch-protection requirements, then merge with GitHub's allowed
|
|
71
|
+
strategy. Running `gh pr merge "$PR_NUMBER"` without a strategy flag lets the
|
|
72
|
+
CLI prompt for one of the repository's permitted methods. Do not select an
|
|
73
|
+
administrator bypass.
|
|
56
74
|
|
|
57
75
|
```bash
|
|
58
|
-
gh
|
|
59
|
-
--add-topic technical-seo \
|
|
60
|
-
--add-topic seo \
|
|
61
|
-
--add-topic ssr \
|
|
62
|
-
--add-topic streaming-html \
|
|
63
|
-
--add-topic nextjs \
|
|
64
|
-
--add-topic nuxt \
|
|
65
|
-
--add-topic astro \
|
|
66
|
-
--add-topic crawler \
|
|
67
|
-
--add-topic typescript \
|
|
68
|
-
--add-topic cli \
|
|
69
|
-
--add-topic seo-tools \
|
|
70
|
-
--add-topic github-actions \
|
|
71
|
-
--add-topic sarif
|
|
76
|
+
gh pr merge "$PR_NUMBER"
|
|
72
77
|
```
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
|
|
79
|
+
After GitHub reports the pull request as merged, update local `main` and wait
|
|
80
|
+
for the CI run on the exact merged commit:
|
|
76
81
|
|
|
77
82
|
```bash
|
|
78
|
-
|
|
83
|
+
git switch main
|
|
84
|
+
git pull --ff-only origin main
|
|
85
|
+
git status --short
|
|
86
|
+
gh pr view "$PR_NUMBER" --json state,mergedAt,mergeCommit
|
|
87
|
+
COMMIT_SHA="$(git rev-parse HEAD)"
|
|
88
|
+
RUN_ID="$(gh run list --workflow CI --branch main --commit "$COMMIT_SHA" \
|
|
89
|
+
--limit 1 --json databaseId --jq '.[0].databaseId')"
|
|
90
|
+
test -n "$RUN_ID"
|
|
91
|
+
gh run watch "$RUN_ID" --exit-status
|
|
79
92
|
```
|
|
80
93
|
|
|
81
|
-
|
|
82
|
-
|
|
94
|
+
`git status --short` must be empty. Do not publish until the merged-commit CI
|
|
95
|
+
run succeeds.
|
|
83
96
|
|
|
84
|
-
|
|
97
|
+
## 4. Verify npm state
|
|
85
98
|
|
|
86
|
-
|
|
99
|
+
```bash
|
|
100
|
+
npm view ssrwire version dist-tags homepage keywords repository.url --json
|
|
101
|
+
npm config get registry
|
|
102
|
+
npm config get provenance
|
|
103
|
+
```
|
|
87
104
|
|
|
88
|
-
|
|
105
|
+
The published version and `latest` tag must still be `0.2.0`. If npm already
|
|
106
|
+
reports `0.3.0`, stop: never reuse a version that npm accepted.
|
|
89
107
|
|
|
90
|
-
|
|
108
|
+
In the npm package settings, select **Require two-factor authentication and
|
|
109
|
+
disallow tokens**. npm documents this as the strongest package publishing
|
|
110
|
+
setting:
|
|
91
111
|
|
|
92
|
-
|
|
93
|
-
|
|
112
|
+
- <https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/>
|
|
113
|
+
- <https://docs.npmjs.com/about-two-factor-authentication/>
|
|
94
114
|
|
|
95
|
-
|
|
96
|
-
npm ci
|
|
97
|
-
npm run check
|
|
98
|
-
npm pack --dry-run
|
|
99
|
-
npm view ssrwire
|
|
100
|
-
```
|
|
115
|
+
## 5. Publish interactively
|
|
101
116
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
session remains fresh for publication:
|
|
117
|
+
Remove inherited automation credentials before starting the interactive
|
|
118
|
+
session:
|
|
105
119
|
|
|
106
120
|
```bash
|
|
121
|
+
unset NODE_AUTH_TOKEN NPM_TOKEN NPM_CONFIG_OTP npm_config_otp
|
|
107
122
|
npm login --auth-type=web --registry=https://registry.npmjs.org
|
|
108
123
|
npm whoami --registry=https://registry.npmjs.org
|
|
109
124
|
npm publish --access public --registry=https://registry.npmjs.org
|
|
@@ -111,24 +126,23 @@ npm view ssrwire version dist-tags homepage keywords repository.url --json
|
|
|
111
126
|
npm logout --registry=https://registry.npmjs.org
|
|
112
127
|
```
|
|
113
128
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
129
|
+
Complete npm's browser, passkey, or two-factor-authentication challenge when
|
|
130
|
+
prompted. Do not use a token with bypass 2FA, put an OTP in a command argument,
|
|
131
|
+
or add an npm credential to the repository or GitHub Actions. The package-level
|
|
132
|
+
"disallow tokens" setting ensures that publication remains interactive.
|
|
118
133
|
|
|
119
|
-
If
|
|
120
|
-
|
|
121
|
-
version again.
|
|
134
|
+
If npm's publish-time scanning delays package visibility, wait. Do not publish
|
|
135
|
+
`0.3.0` again or change the tag to work around propagation.
|
|
122
136
|
|
|
123
|
-
|
|
137
|
+
## 6. Tag the exact published commit
|
|
124
138
|
|
|
125
139
|
```bash
|
|
126
140
|
node scripts/clean.mjs
|
|
127
141
|
rm -rf node_modules/.vite
|
|
128
142
|
git status --short
|
|
129
|
-
git tag -a v0.
|
|
130
|
-
git push origin v0.
|
|
131
|
-
gh release create v0.
|
|
143
|
+
git tag -a v0.3.0 -m "SSRWire v0.3.0"
|
|
144
|
+
git push origin v0.3.0
|
|
145
|
+
gh release create v0.3.0 --generate-notes --title "SSRWire v0.3.0"
|
|
132
146
|
```
|
|
133
147
|
|
|
134
|
-
`git status --short` must print nothing before tagging
|
|
148
|
+
`git status --short` must print nothing before tagging.
|
package/README.md
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
# SSRWire
|
|
2
2
|
|
|
3
3
|
[](https://github.com/lame13/ssrwire/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/ssrwire)
|
|
4
5
|
[](LICENSE)
|
|
5
6
|
|
|
6
|
-
Inspect streamed SSR HTML, metadata timing, and crawler-specific
|
|
7
|
-
the command line.
|
|
7
|
+
Inspect streamed SSR HTML, SEO and social metadata timing, and crawler-specific
|
|
8
|
+
delivery from the command line.
|
|
8
9
|
|
|
9
10
|
SSRWire makes a real HTTP request for each selected user-agent profile, reads
|
|
10
|
-
the response incrementally, and records when important SEO
|
|
11
|
-
observable to its parser. It reports their elapsed time,
|
|
12
|
-
position, and document location without launching a browser or
|
|
13
|
-
JavaScript.
|
|
11
|
+
the response incrementally, and records when important SEO and social-preview
|
|
12
|
+
signals become observable to its parser. It reports their elapsed time,
|
|
13
|
+
observed byte position, and document location without launching a browser or
|
|
14
|
+
executing JavaScript.
|
|
14
15
|
|
|
15
16
|
```bash
|
|
16
17
|
npx ssrwire https://example.com/product
|
|
@@ -24,7 +25,9 @@ Modern SSR output is not always one complete HTML document delivered at once:
|
|
|
24
25
|
- a framework may intentionally stream metadata into `<body>` for a capable
|
|
25
26
|
crawler while blocking for an HTML-limited bot;
|
|
26
27
|
- browser, search-crawler, and social-crawler user agents may receive different
|
|
27
|
-
titles, canonicals, robots directives, redirects, or
|
|
28
|
+
titles, canonicals, social-preview metadata, robots directives, redirects, or
|
|
29
|
+
statuses;
|
|
30
|
+
- the same URL and user agent may receive inconsistent SSR output between requests;
|
|
28
31
|
- an interrupted or oversized stream may never deliver the expected elements;
|
|
29
32
|
- a working hydrated page can hide thin or incomplete source HTML.
|
|
30
33
|
|
|
@@ -84,13 +87,13 @@ form of `npx ssrwire check URL`.
|
|
|
84
87
|
|
|
85
88
|
## What it observes
|
|
86
89
|
|
|
87
|
-
For each target and
|
|
90
|
+
For each target, agent, and configured sample, SSRWire captures:
|
|
88
91
|
|
|
89
92
|
- response status, final URL, redirect chain, and an allowlisted response-header snapshot;
|
|
90
93
|
- time to response headers, first response-body bytes, and completed body;
|
|
91
94
|
- total bytes delivered to the stream parser and a body fingerprint;
|
|
92
|
-
- title, meta description, canonical, meta robots,
|
|
93
|
-
text, and JSON-LD blocks;
|
|
95
|
+
- title, meta description, canonical, meta robots, Open Graph, Twitter Card,
|
|
96
|
+
H1, first main-content text, and JSON-LD blocks;
|
|
94
97
|
- elapsed arrival time, observed byte position, and `head`/`body` location for
|
|
95
98
|
each signal;
|
|
96
99
|
- clean completion, timeout, network failure, invalid response, or configured
|
|
@@ -105,10 +108,15 @@ It then checks:
|
|
|
105
108
|
| Missing title | Error |
|
|
106
109
|
| Missing description, canonical, H1, or main text | Warning |
|
|
107
110
|
| Duplicate or conflicting title, description, canonical, or robots values | Warning |
|
|
111
|
+
| Missing an enabled Open Graph or Twitter Card contract | Warning |
|
|
112
|
+
| Invalid social metadata URL or conflicting scalar social metadata | Warning |
|
|
108
113
|
| Invalid JSON-LD | Warning |
|
|
109
114
|
| JSON-LD block/count exceeds the bounded analysis budget | Warning |
|
|
110
|
-
| Critical metadata in `<body>` for a profile that requires head metadata | Error |
|
|
111
|
-
| Status, final URL, title, canonical, or
|
|
115
|
+
| Critical or enabled social metadata in `<body>` for a profile that requires head metadata | Error |
|
|
116
|
+
| Status, final URL, title, canonical, robots, or enabled social metadata drift between profiles | Warning |
|
|
117
|
+
| Completion, status, final URL, or redirect-chain drift between samples | Warning |
|
|
118
|
+
| Metadata value or document-location drift between complete samples | Warning |
|
|
119
|
+
| Exact body fingerprint drift without metadata drift | Information |
|
|
112
120
|
| First byte or required-signal arrival over a configured limit | Warning |
|
|
113
121
|
| Timeout, truncation, network error, or another incomplete probe | Error / incomplete run |
|
|
114
122
|
|
|
@@ -157,6 +165,41 @@ agents:
|
|
|
157
165
|
requiresHeadMetadata: true
|
|
158
166
|
```
|
|
159
167
|
|
|
168
|
+
## Social preview metadata
|
|
169
|
+
|
|
170
|
+
Every probe captures these bounded, ordered metadata signals when they arrive
|
|
171
|
+
before completion or termination:
|
|
172
|
+
|
|
173
|
+
- Open Graph: `og:title`, `og:type`, `og:url`, `og:image`, and
|
|
174
|
+
`og:description`;
|
|
175
|
+
- Twitter Card: `twitter:card`, `twitter:title`, `twitter:description`, and
|
|
176
|
+
`twitter:image`.
|
|
177
|
+
|
|
178
|
+
SSRWire accepts either the conventional `property` attribute or a `name`
|
|
179
|
+
attribute for those keys. Each captured value carries the same arrival time,
|
|
180
|
+
observed byte position, and document location as the existing metadata
|
|
181
|
+
signals. The terminal report shows a compact readiness table whenever social
|
|
182
|
+
metadata is observed or required, while JSON retains every captured value.
|
|
183
|
+
|
|
184
|
+
Social policy is opt-in per target. `openGraph: true` requires the four basic
|
|
185
|
+
[Open Graph protocol](https://ogp.me/) properties: title, type, URL, and image.
|
|
186
|
+
The `twitterCard: true` option requires `twitter:card` plus a usable title,
|
|
187
|
+
description, and image; SSRWire prefers the corresponding `twitter:*` value
|
|
188
|
+
and falls back to `og:title`, `og:description`, or `og:image`. These are
|
|
189
|
+
explicit SSRWire audit contracts, not a claim that a social platform will
|
|
190
|
+
render a particular preview.
|
|
191
|
+
|
|
192
|
+
Enabled contracts also participate in critical-signal timing, head/body
|
|
193
|
+
policy, cross-agent drift, and repeated-sample stability checks. URL-valued
|
|
194
|
+
fields must be absolute HTTP or HTTPS URLs. Open Graph permits multiple images,
|
|
195
|
+
so SSRWire retains them in order without treating the array as a scalar
|
|
196
|
+
conflict; the first non-empty image satisfies readiness.
|
|
197
|
+
|
|
198
|
+
When both options are false, SSRWire still records and reports raw social
|
|
199
|
+
signals but emits no social-policy or social-drift findings. It does not fetch
|
|
200
|
+
images, verify dimensions or media types, execute JavaScript, or simulate a
|
|
201
|
+
platform's rendered preview.
|
|
202
|
+
|
|
160
203
|
## Configuration
|
|
161
204
|
|
|
162
205
|
SSRWire automatically looks for `ssrwire.config.yml`,
|
|
@@ -174,6 +217,8 @@ targets:
|
|
|
174
217
|
canonical: true
|
|
175
218
|
h1: true
|
|
176
219
|
mainText: true
|
|
220
|
+
openGraph: true
|
|
221
|
+
twitterCard: true
|
|
177
222
|
maxFirstByteMs: 1200
|
|
178
223
|
maxCriticalMs: 2500
|
|
179
224
|
|
|
@@ -185,6 +230,8 @@ targets:
|
|
|
185
230
|
canonical: false
|
|
186
231
|
h1: true
|
|
187
232
|
mainText: true
|
|
233
|
+
openGraph: false
|
|
234
|
+
twitterCard: false
|
|
188
235
|
|
|
189
236
|
agents:
|
|
190
237
|
- browser
|
|
@@ -198,6 +245,7 @@ headers:
|
|
|
198
245
|
timeoutMs: 15000
|
|
199
246
|
maxBytes: 10485760
|
|
200
247
|
maxRedirects: 10
|
|
248
|
+
repeat: 1
|
|
201
249
|
```
|
|
202
250
|
|
|
203
251
|
A target can also be a plain URL string when defaults are sufficient:
|
|
@@ -212,10 +260,12 @@ Defaults:
|
|
|
212
260
|
|
|
213
261
|
- expected status: `200`;
|
|
214
262
|
- title, description, canonical, H1, and main text: required;
|
|
263
|
+
- Open Graph and Twitter Card contracts: disabled;
|
|
215
264
|
- agents: `browser`, `googlebot`, `bingbot`, and `twitterbot`;
|
|
216
265
|
- timeout: 15 seconds per probe;
|
|
217
266
|
- response limit: 10 MiB;
|
|
218
|
-
- redirect limit: 10
|
|
267
|
+
- redirect limit: 10;
|
|
268
|
+
- samples per target and agent: 1, with an allowed range of 1–10.
|
|
219
269
|
|
|
220
270
|
Unknown configuration keys are rejected. URLs must be absolute HTTP or HTTPS
|
|
221
271
|
URLs and cannot contain embedded credentials.
|
|
@@ -255,11 +305,11 @@ The final response must declare `text/html` or `application/xhtml+xml` as its
|
|
|
255
305
|
sniff headerless, JSON, text, or binary responses for HTML-looking fragments.
|
|
256
306
|
|
|
257
307
|
To keep hostile or accidentally huge pages bounded, SSRWire retains at most
|
|
258
|
-
256 signals of each repeated metadata kind,
|
|
259
|
-
and captures at most 1,048,576
|
|
260
|
-
JSON-LD
|
|
261
|
-
mislabeled as invalid JSON. The
|
|
262
|
-
outer bound.
|
|
308
|
+
256 signals of each repeated metadata kind, including each supported social
|
|
309
|
+
property, analyzes at most 64 JSON-LD blocks, and captures at most 1,048,576
|
|
310
|
+
characters from one JSON-LD block. Exceeding a JSON-LD analysis budget produces
|
|
311
|
+
a dedicated warning rather than being mislabeled as invalid JSON. The
|
|
312
|
+
configured response-byte limit remains the outer bound.
|
|
263
313
|
|
|
264
314
|
## Timing interpretation
|
|
265
315
|
|
|
@@ -276,6 +326,40 @@ transfer-size or packet-boundary evidence. They count bytes delivered by the
|
|
|
276
326
|
Fetch implementation to SSRWire; those bytes are post-content-decoding when a
|
|
277
327
|
server ignores SSRWire's `Accept-Encoding: identity` request.
|
|
278
328
|
|
|
329
|
+
## Repeated sampling
|
|
330
|
+
|
|
331
|
+
Use repeated sampling when one successful request does not prove that SSR output
|
|
332
|
+
is stable:
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
npx ssrwire check --repeat 3
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
`repeat` is the total number of samples, not a retry count. SSRWire retains
|
|
339
|
+
failures instead of replacing them with a later success. Samples for one
|
|
340
|
+
target-agent pair run sequentially; different target-agent pairs may still run
|
|
341
|
+
concurrently. SSRWire does not add delays, cache-busting parameters, or special
|
|
342
|
+
cache headers.
|
|
343
|
+
|
|
344
|
+
The request count is `targets × agents × repeat`, plus redirect hops. Configured
|
|
345
|
+
same-origin headers are sent for every sample and retain the existing
|
|
346
|
+
cross-origin stripping and report-redaction behavior.
|
|
347
|
+
|
|
348
|
+
For repeated runs, terminal reports include individual sample numbers and a
|
|
349
|
+
per-agent timing table. JSON retains every probe and adds per-agent stability
|
|
350
|
+
summaries. The summaries report sample count, minimum, median, nearest-rank p95,
|
|
351
|
+
maximum, and spread for available header, first-byte, required-signal, and
|
|
352
|
+
completion timings. With small sample counts, nearest-rank p95 will often equal
|
|
353
|
+
the maximum.
|
|
354
|
+
|
|
355
|
+
Timing spread alone is evidence, not a failure. Network and cache variation can
|
|
356
|
+
change timings without changing the response contract. SSRWire warns when HTTP
|
|
357
|
+
response evidence or streamed metadata changes across samples. Enabled social
|
|
358
|
+
contracts are included in metadata stability; observed social tags remain
|
|
359
|
+
evidence-only when their contracts are disabled. Exact body-hash variation by
|
|
360
|
+
itself is informational because timestamps, nonces, and other legitimate
|
|
361
|
+
dynamic values commonly change source HTML.
|
|
362
|
+
|
|
279
363
|
## CLI reference
|
|
280
364
|
|
|
281
365
|
```text
|
|
@@ -294,6 +378,7 @@ Check options:
|
|
|
294
378
|
| `--timeout <ms>` | Override request timeout |
|
|
295
379
|
| `--max-bytes <bytes>` | Override response-body limit |
|
|
296
380
|
| `--max-redirects <count>` | Override redirect limit |
|
|
381
|
+
| `--repeat <count>` | Run 1–10 sequential samples per URL and agent |
|
|
297
382
|
| `-f, --format <format>` | `terminal`, `json`, or `sarif` |
|
|
298
383
|
| `-o, --output <path>` | Write the report to a file |
|
|
299
384
|
| `--fail-on <level>` | `error`, `warning`, or `never` |
|
|
@@ -304,9 +389,10 @@ removed.
|
|
|
304
389
|
|
|
305
390
|
## Reports and exit codes
|
|
306
391
|
|
|
307
|
-
- `terminal`: compact
|
|
392
|
+
- `terminal`: compact sample, social-readiness, aggregate-timing, and finding
|
|
393
|
+
tables for local use.
|
|
308
394
|
- `json`: structured machine-readable evidence, including every probe and timing
|
|
309
|
-
signal.
|
|
395
|
+
signal plus repeated-run stability summaries.
|
|
310
396
|
- `sarif`: findings suitable for GitHub Code Scanning and other SARIF 2.1.0
|
|
311
397
|
consumers.
|
|
312
398
|
|
|
@@ -369,7 +455,7 @@ by the CLI:
|
|
|
369
455
|
```ts
|
|
370
456
|
import { loadConfig, renderJson, runAudit } from "ssrwire";
|
|
371
457
|
|
|
372
|
-
const config = await loadConfig({ urls: ["https://example.com/"] });
|
|
458
|
+
const config = await loadConfig({ urls: ["https://example.com/"], repeat: 3 });
|
|
373
459
|
const audit = await runAudit(config);
|
|
374
460
|
process.stdout.write(renderJson(audit));
|
|
375
461
|
```
|
|
@@ -380,15 +466,18 @@ versions.
|
|
|
380
466
|
|
|
381
467
|
## Scope
|
|
382
468
|
|
|
383
|
-
SSRWire does not execute JavaScript, inspect a hydrated DOM,
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
469
|
+
SSRWire does not execute JavaScript, inspect a hydrated DOM, render social
|
|
470
|
+
previews, fetch social images, measure Core Web Vitals, discover URLs, validate
|
|
471
|
+
indexing, bypass access controls, perform load testing, or emulate a crawler's
|
|
472
|
+
rendering pipeline. Use
|
|
473
|
+
[RoutePlay](https://github.com/lame13/routeplay) for server HTML versus a cold
|
|
474
|
+
browser versus real client-side navigation. Use
|
|
475
|
+
[RouteLint](https://github.com/lame13/routelint) for route discovery,
|
|
476
|
+
indexability, and technical SEO policy.
|
|
388
477
|
|
|
389
478
|
Run SSRWire only against targets you are authorized to inspect. Keep target
|
|
390
|
-
lists intentionally small
|
|
391
|
-
|
|
479
|
+
lists and repeat counts intentionally small. It is a consistency sampler, not a
|
|
480
|
+
load generator.
|
|
392
481
|
|
|
393
482
|
## Development
|
|
394
483
|
|
package/SECURITY.md
CHANGED
|
@@ -20,7 +20,11 @@ report. You should receive an initial response within seven days.
|
|
|
20
20
|
## Operational safety
|
|
21
21
|
|
|
22
22
|
SSRWire sends real HTTP requests to every configured target for every selected
|
|
23
|
-
agent profile
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
agent profile and sample. The base request count is
|
|
24
|
+
`targets × agents × repeat`, plus redirect hops. Samples for one target-agent
|
|
25
|
+
pair are sequential, but different pairs may run concurrently. Keep `repeat`
|
|
26
|
+
bounded and use SSRWire only against systems you are authorized to test.
|
|
27
|
+
|
|
28
|
+
Treat custom headers as secrets and remember that they are sent on every
|
|
29
|
+
same-origin sample. Prefer environment-variable interpolation, and do not
|
|
30
|
+
commit populated `.env` files or generated reports containing private URLs.
|
package/dist/analyze.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,OAAO,EACP,WAAW,EAMX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AA2pBpB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,SAAS,OAAO,EAAE,CAwGpB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,YAAY,CA6BlF"}
|