@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1
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 +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- package/package.json +191 -4
|
@@ -0,0 +1,547 @@
|
|
|
1
|
+
# Wire format v1
|
|
2
|
+
|
|
3
|
+
The contract between every Starko SDK and the Starko ingest API. The typed
|
|
4
|
+
version is [`src/types/wire.ts`](../src/types/wire.ts); valid examples are in
|
|
5
|
+
[`fixtures/wire/`](../fixtures/wire). The SDKs are thin producers of this
|
|
6
|
+
format: anything that can send this JSON can report errors to Starko.
|
|
7
|
+
|
|
8
|
+
## Send errors
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
POST {host}/api/v1/ingest/errors
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
- `host` defaults to `https://v2.starko.one`.
|
|
15
|
+
- The body is JSON, optionally gzip-compressed (`Content-Encoding: gzip`, or
|
|
16
|
+
detected by the gzip magic bytes). Any `Content-Type` is accepted; browsers
|
|
17
|
+
send `text/plain` so the request needs no CORS preflight.
|
|
18
|
+
- The **workspace key** goes in the body (`workspace`). It is the workspace id
|
|
19
|
+
shown in Starko under Settings. It is public: it only lets a caller send
|
|
20
|
+
errors, never read anything.
|
|
21
|
+
- A server may also send a **secret key** (`Authorization: Bearer sk_starko_…`
|
|
22
|
+
with the `errors:write` scope, created in Starko under Settings). It is
|
|
23
|
+
optional. With it, the events are trusted: the `user.id` they name is linked
|
|
24
|
+
without a hash, and the per-IP limits do not apply. Never ship a secret key
|
|
25
|
+
to a browser.
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"v": 1,
|
|
30
|
+
"workspace": "3ba57953-699d-4385-bc68-08fd6e7d9226",
|
|
31
|
+
"sdk": { "name": "starko.browser", "version": "0.1.0-beta.1" },
|
|
32
|
+
"sent_at": 1795000000500,
|
|
33
|
+
"events": [
|
|
34
|
+
{
|
|
35
|
+
"event_id": "0b0e7a52-5c1f-4c58-9a57-6f1d2f0c9a11",
|
|
36
|
+
"timestamp": 1795000000000,
|
|
37
|
+
"platform": "browser",
|
|
38
|
+
"level": "error",
|
|
39
|
+
"exception_list": [
|
|
40
|
+
{
|
|
41
|
+
"type": "TypeError",
|
|
42
|
+
"value": "Cannot read properties of undefined (reading 'total')",
|
|
43
|
+
"mechanism": { "type": "onerror", "handled": false },
|
|
44
|
+
"stacktrace": {
|
|
45
|
+
"type": "raw",
|
|
46
|
+
"frames": [
|
|
47
|
+
{
|
|
48
|
+
"platform": "web:javascript",
|
|
49
|
+
"filename": "https://shop.example.com/assets/checkout-4f9a2c.js",
|
|
50
|
+
"function": "renderTotals",
|
|
51
|
+
"lineno": 1,
|
|
52
|
+
"colno": 48213,
|
|
53
|
+
"in_app": true,
|
|
54
|
+
"chunk_id": "5b1f6c0e-7a55-5d0e-9d0c-2f4f8b7a9e10"
|
|
55
|
+
}
|
|
56
|
+
]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
],
|
|
60
|
+
"release": "shop@4.12.0",
|
|
61
|
+
"environment": "production",
|
|
62
|
+
"session_id": "b2f7c1de-1c7c-4a1c-9d3f-9f5d7f0e6a55",
|
|
63
|
+
"user": { "id": "user_123", "email": "ana@example.com" },
|
|
64
|
+
"request": { "url": "https://shop.example.com/checkout?step=2" },
|
|
65
|
+
"tags": { "plan": "pro" },
|
|
66
|
+
"breadcrumbs": [
|
|
67
|
+
{ "timestamp": 1794999998000, "type": "ui", "category": "click", "message": "button#pay" }
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
]
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Envelope
|
|
75
|
+
|
|
76
|
+
| Field | Required | Meaning |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `v` | yes | Always `1`. |
|
|
79
|
+
| `workspace` | yes | Workspace key. |
|
|
80
|
+
| `sdk` | yes | `name` and `version` of the sender. |
|
|
81
|
+
| `sent_at` | yes | Sender's clock (epoch ms) when this request left. Set it again on every retry. |
|
|
82
|
+
| `events` | yes | 1 to 20 events. |
|
|
83
|
+
|
|
84
|
+
### Event
|
|
85
|
+
|
|
86
|
+
| Field | Required | Meaning |
|
|
87
|
+
| --- | --- | --- |
|
|
88
|
+
| `event_id` | yes | UUID minted by the sender. An event id is counted once per workspace, so a retry never double-counts. |
|
|
89
|
+
| `timestamp` | yes | Epoch ms when the error happened, on the sender's clock. |
|
|
90
|
+
| `platform` | yes | `browser`, `node`, `dotnet`, `php`, `python`, `ruby`, `go`, `java` or `other`. |
|
|
91
|
+
| `level` | yes | `fatal`, `error`, `warning`, `info` or `debug`. Only `error` and `fatal` can file a ticket. |
|
|
92
|
+
| `exception_list` | yes | The thrown error first, then its causes. At least one. |
|
|
93
|
+
| `fingerprint` | no | Custom grouping key: events with the same value become one issue. |
|
|
94
|
+
| `release` | no | App version. Frames are resolved by `chunk_id`, not by release; send the release the source maps were uploaded for. |
|
|
95
|
+
| `environment` | no | `production`, `staging`, … |
|
|
96
|
+
| `session_id` | no | Session shared with the Starko widget and session replay. |
|
|
97
|
+
| `user` | no | `id` (your own user id), `email`, `name`, `hash`. See identity below. |
|
|
98
|
+
| `client_token` | no | The Starko widget's client token when the widget is on the page. |
|
|
99
|
+
| `request` | no | `url`, `method`, `route`, `referrer`. |
|
|
100
|
+
| `user_agent` | no | For server SDKs forwarding a browser's user agent. |
|
|
101
|
+
| `server_name` | no | Host that captured the event. |
|
|
102
|
+
| `tags` | no | String key/value pairs you can filter on. |
|
|
103
|
+
| `extra` | no | Free-form JSON shown on the occurrence. |
|
|
104
|
+
| `contexts` | no | Named blocks such as `runtime`, `os`, `browser`. |
|
|
105
|
+
| `breadcrumbs` | no | What happened before the error, oldest first. |
|
|
106
|
+
| `trace` | no | `trace_id`, `span_id`. |
|
|
107
|
+
|
|
108
|
+
**Time.** The server corrects `timestamp` by the clock skew it sees
|
|
109
|
+
(receipt time minus `sent_at`, applied when larger than 5 minutes), then
|
|
110
|
+
replaces it with the receipt time when it is still more than 24 hours off.
|
|
111
|
+
|
|
112
|
+
### Exception
|
|
113
|
+
|
|
114
|
+
| Field | Required | Meaning |
|
|
115
|
+
| --- | --- | --- |
|
|
116
|
+
| `type` | yes | Error class name. |
|
|
117
|
+
| `value` | yes | Message. |
|
|
118
|
+
| `module` | no | Namespace or module of the error class. |
|
|
119
|
+
| `mechanism` | no | `type` (what caught it), `handled` (false for unhandled), `synthetic`, and `source` / `exception_id` / `parent_id` for chains. |
|
|
120
|
+
| `stacktrace` | no | `{ "type": "raw", "frames": [...] }`. |
|
|
121
|
+
|
|
122
|
+
**Frames are ordered most recent call first**: `frames[0]` is where the error
|
|
123
|
+
was thrown. Some other SDKs (Sentry's, for one) send the opposite order; code
|
|
124
|
+
adapted from their parsers must not reverse.
|
|
125
|
+
|
|
126
|
+
### Frame
|
|
127
|
+
|
|
128
|
+
| Field | Required | Meaning |
|
|
129
|
+
| --- | --- | --- |
|
|
130
|
+
| `platform` | yes | `web:javascript`, `node:javascript` or `custom`. |
|
|
131
|
+
| `lang` | for `custom` | Lowercase language name: `dotnet`, `php`, `python`, … |
|
|
132
|
+
| `filename` | no | Script URL or file path. |
|
|
133
|
+
| `abs_path` | no | Absolute path when `filename` is relative. |
|
|
134
|
+
| `function` | no | Function or method name. |
|
|
135
|
+
| `module` | no | Module, namespace or class. |
|
|
136
|
+
| `lineno`, `colno` | no | 1-based. |
|
|
137
|
+
| `in_app` | no | `false` for dependencies and runtime internals. When absent, the server decides. |
|
|
138
|
+
| `chunk_id` | no | Debug id of the bundle; the server finds the source map by it. |
|
|
139
|
+
| `context_line`, `pre_context`, `post_context` | no | Source lines around the frame, when the sender can read source. |
|
|
140
|
+
| `resolved` | no | `true` when the frame already shows original source. Honoured on `custom` frames only. |
|
|
141
|
+
|
|
142
|
+
JavaScript frames from a minified bundle are resolved on the server with the
|
|
143
|
+
uploaded source map, whatever `resolved` says. `custom` frames are stored as
|
|
144
|
+
sent: languages that run their source directly (PHP, Python) or carry debug
|
|
145
|
+
info (.NET) need no upload.
|
|
146
|
+
|
|
147
|
+
The server only ever uses source maps that were uploaded to it. It never
|
|
148
|
+
fetches a script or a source map from a URL found in an event.
|
|
149
|
+
|
|
150
|
+
### Responses
|
|
151
|
+
|
|
152
|
+
Every response is JSON: `{ "ok": boolean, "message": string, "data": … }`.
|
|
153
|
+
When a request is not accepted, `data.reason` says why.
|
|
154
|
+
|
|
155
|
+
| Status | `data.reason` | Meaning | What a sender does |
|
|
156
|
+
| --- | --- | --- | --- |
|
|
157
|
+
| 200 | | `data: { accepted, rejected }`. Rejected events failed validation; the rest were taken. | Nothing. |
|
|
158
|
+
| 3xx | | A proxy or a misconfigured `host` (`http://`, an apex domain). The ingest API never redirects. | Do NOT follow it (the POST would become a GET and the key would go to another host): drop the batch and tell the user, naming the `Location`. |
|
|
159
|
+
| 400 | `invalid`, `unsupported_version` | Malformed envelope, or a `v` the server does not speak (`data.supported_versions`). | Drop the batch. |
|
|
160
|
+
| 401 | `invalid` | A secret key was presented (`Authorization: Bearer …`) and is not valid. | A configuration error: drop the batch without retrying and tell the user once (the Starko SDKs print `secret key refused`); fix or remove the key. |
|
|
161
|
+
| 401 | `unknown_workspace` | Unknown workspace key. | Stop sending for this page load or process. |
|
|
162
|
+
| 403 | `disabled` | Error tracking is off for the workspace (`data.enabled` is `false`). | Stop sending for this page load or process. |
|
|
163
|
+
| 403 | `origin_not_allowed` | The page's origin is not on the workspace's allow-list. | Stop sending for this page load. |
|
|
164
|
+
| 413 | `too_large` | Body too large. | Halve the batch and retry once. |
|
|
165
|
+
| 429 | `rate_limit` | Too many requests. `Retry-After` in seconds. | Wait, then retry. |
|
|
166
|
+
| 429 | `quota` | The workspace's allowance is used up. `Retry-After` is long. | Drop the batch; do not retry until `Retry-After` has passed. |
|
|
167
|
+
| 503 | `busy` | The server is shedding load or its queue store is unavailable. `Retry-After` in seconds (30 for an unavailable store). | Wait at least `Retry-After`, then retry. |
|
|
168
|
+
|
|
169
|
+
Rules for every sender:
|
|
170
|
+
|
|
171
|
+
- **Switch off only on an explicit answer.** A sender disables itself only
|
|
172
|
+
when the body is JSON of the shape above with `reason` `unknown_workspace`,
|
|
173
|
+
`disabled` or `origin_not_allowed`. A 401 or 403 with any other body (a
|
|
174
|
+
proxy, a firewall, a captive portal) is a temporary failure.
|
|
175
|
+
- **At most three attempts** per batch, with backoff and jitter, honouring
|
|
176
|
+
`Retry-After`. A request that gets no answer within a deadline (10 to 15
|
|
177
|
+
seconds in a browser) is aborted and counts as a network failure. After
|
|
178
|
+
repeated failures a sender pauses for a few minutes (never for the rest of
|
|
179
|
+
a page load: a long-lived single-page app must not go quiet after a short
|
|
180
|
+
offline period), resumes earlier when the browser reports it is back
|
|
181
|
+
`online`, and keeps only a bounded queue.
|
|
182
|
+
- **Never follow a redirect**, on the ingest or the config request.
|
|
183
|
+
- **Unknown things are ignored**: fields a receiver does not know, an unknown
|
|
184
|
+
`platform` (treated as `other`), an unknown `level` (treated as `error`).
|
|
185
|
+
|
|
186
|
+
### Limits
|
|
187
|
+
|
|
188
|
+
Lengths are JavaScript string lengths.
|
|
189
|
+
|
|
190
|
+
| What | Limit |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| Events per request | 20 |
|
|
193
|
+
| Body | 512 KiB as sent, 2 MiB decompressed |
|
|
194
|
+
| JSON nesting depth | 20 |
|
|
195
|
+
| Exceptions per event | 10 (the first 10 are kept) |
|
|
196
|
+
| Frames per exception | 50 (the 25 most recent and the 25 oldest are kept) |
|
|
197
|
+
| Distinct `chunk_id`s resolved per event | 8 |
|
|
198
|
+
| `type` / `value` | 200 / 2000 |
|
|
199
|
+
| `filename`, `abs_path` / `function`, `module` | 1000 / 300 |
|
|
200
|
+
| Context lines | 7 before, 7 after, 300 each |
|
|
201
|
+
| Breadcrumbs | 50, 32 KiB in total |
|
|
202
|
+
| Tags | 50, key 64 and value 256 |
|
|
203
|
+
| `extra`, `contexts` | 16 KiB each |
|
|
204
|
+
| `fingerprint` / `release` / `environment` | 128 / 128 / 64 |
|
|
205
|
+
| URLs | 2048 |
|
|
206
|
+
| `session_id` | 8 to 70 of `A-Z a-z 0-9 -` |
|
|
207
|
+
|
|
208
|
+
The server truncates strings and arrays beyond these and rejects an event or
|
|
209
|
+
request beyond the size and depth limits.
|
|
210
|
+
|
|
211
|
+
The server also protects a workspace from floods: requests per IP and per
|
|
212
|
+
workspace per minute, a monthly allowance spent at most a share per day and
|
|
213
|
+
per IP, a cap on new issues per hour, and one daily cap on tickets filed
|
|
214
|
+
automatically. The exact numbers are server policy, not part of this format.
|
|
215
|
+
|
|
216
|
+
### Identity
|
|
217
|
+
|
|
218
|
+
An event is linked to a customer in Starko by a credential. The credentials
|
|
219
|
+
an event carries are checked in this order, and the first one that gives a
|
|
220
|
+
verified link wins; the next one is checked only when the one before it
|
|
221
|
+
gave none:
|
|
222
|
+
|
|
223
|
+
1. `client_token`: the widget's own token. The link is verified when the
|
|
224
|
+
token's customer is in this workspace and their profile is anonymous or
|
|
225
|
+
identity-verified. For a customer who was identified in the widget
|
|
226
|
+
without verification (an email typed into it, `identify` without a
|
|
227
|
+
hash) the event is still linked, and Starko labels the link
|
|
228
|
+
"unverified" wherever it shows it; a verified link from 2 or 3 replaces
|
|
229
|
+
it. A token that does not verify links nobody.
|
|
230
|
+
2. `user.id` or `user.email` with a valid `user.hash`. The hash is the one the
|
|
231
|
+
widget's `identify` uses: an HMAC-SHA256 (hex) computed by your backend
|
|
232
|
+
with the workspace identity secret, over `user.id` when `user.id` is set,
|
|
233
|
+
otherwise over `user.email`.
|
|
234
|
+
3. `user.id` in a request authenticated with a secret key (server SDKs),
|
|
235
|
+
matched to an existing customer's own id. A hash over `user.id` likewise
|
|
236
|
+
matches by id only, never by email.
|
|
237
|
+
|
|
238
|
+
A `user` without any of these is kept on the occurrence as text (the id and
|
|
239
|
+
email the sender claimed) and is never linked to a customer, never shown as
|
|
240
|
+
an affected customer and never attached to a ticket. Error events never
|
|
241
|
+
create customers.
|
|
242
|
+
|
|
243
|
+
`client_token` and `user.hash` are credentials. The server verifies them when
|
|
244
|
+
the request arrives and keeps only the resulting customer id: they are not
|
|
245
|
+
stored, queued or logged. SDKs must not log them either.
|
|
246
|
+
|
|
247
|
+
### Privacy
|
|
248
|
+
|
|
249
|
+
What the SDKs do by default, and the server enforces again:
|
|
250
|
+
|
|
251
|
+
- These URL rules apply to every URL a sender sends: the page URL and
|
|
252
|
+
referrer, request and breadcrumb URLs, frame file names (`filename`,
|
|
253
|
+
`abs_path`; a script loaded from a signed URL), and `http(s)` URLs found
|
|
254
|
+
inside exception messages and breadcrumb messages (the rest of the text is
|
|
255
|
+
left alone).
|
|
256
|
+
- The `#fragment` and the userinfo (`user:pass@`) of every URL are dropped.
|
|
257
|
+
- Query-string values of sensitive parameters (`token`, `code`, `key`,
|
|
258
|
+
`secret`, `password`, `signature`, `session`, `email`, … the list is
|
|
259
|
+
`SENSITIVE_QUERY_PARAMS` in `wire.ts`) are replaced with `[redacted]`. A
|
|
260
|
+
name matches when the whole name or any part of it is on the list, compared
|
|
261
|
+
case-insensitively, with names split on `_`, `-` and camelCase boundaries:
|
|
262
|
+
`access_token`, `accessToken`, `clientSecret`, `apiKey`, `sessionId` and
|
|
263
|
+
`X-Amz-Signature` all match.
|
|
264
|
+
- Click breadcrumbs carry a short selector, never an element's text or an
|
|
265
|
+
input's value, and skip elements the Starko recorder is told to mask
|
|
266
|
+
(`starko-mask`, `starko-no-capture`).
|
|
267
|
+
- Console breadcrumbs cover warnings and errors only, as text cut to 200
|
|
268
|
+
characters.
|
|
269
|
+
- Request and response bodies, cookies and headers are never collected.
|
|
270
|
+
- Server SDKs read source lines (`context_line`, …) only from source files
|
|
271
|
+
(`.js .mjs .cjs .jsx .ts .tsx .mts .cts`) whose real path is inside the
|
|
272
|
+
application's root, never from dotfiles: a stack can name any path.
|
|
273
|
+
- The server scrubs well-known secret formats (card numbers, bearer tokens,
|
|
274
|
+
cloud and API keys, JWTs) from messages, source lines, `extra`, tags and
|
|
275
|
+
breadcrumbs before storing them.
|
|
276
|
+
|
|
277
|
+
## Read the remote config
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
GET {host}/api/v1/ingest/config?workspace=<workspace key>
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
```json
|
|
284
|
+
{ "ok": true, "message": "Ok", "data": { "enabled": true, "sample_rate": 1, "suppress": [{ "value_contains": "ResizeObserver loop" }] } }
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
An SDK reads it once: a browser SDK at start (holding events until it
|
|
288
|
+
arrives), a server SDK just before its first request (so an idle process
|
|
289
|
+
makes no request; events captured before it apply what it says once it
|
|
290
|
+
arrives). `enabled: false` means install nothing and send nothing (and
|
|
291
|
+
drop what is unsent); an unknown workspace gets the same answer. A failed request is
|
|
292
|
+
treated as `enabled: true` with defaults. The response is cacheable for a
|
|
293
|
+
minute. `sample_rate` and `suppress` reduce noise in well-behaved SDKs; they
|
|
294
|
+
are not a protection.
|
|
295
|
+
|
|
296
|
+
## Upload source maps
|
|
297
|
+
|
|
298
|
+
Authenticated with a secret key that has the `sourcemaps:write` scope
|
|
299
|
+
(`Authorization: Bearer sk_starko_…`), created in Starko under Settings.
|
|
300
|
+
The key identifies the workspace. Every answer is JSON,
|
|
301
|
+
`{ "ok": boolean, "message": string, "data": … }`, and a status other than
|
|
302
|
+
200 means the whole request failed (`data` is `null`).
|
|
303
|
+
|
|
304
|
+
`content_hash` is the sha256 (hex) of the **uncompressed** source map.
|
|
305
|
+
`chunk_id` is the debug id the build injected into the bundle: a
|
|
306
|
+
`//# debugId=<uuid>` comment at the end of the file, the same id in the source
|
|
307
|
+
map's `debugId` field, and a snippet that registers it at runtime in
|
|
308
|
+
`globalThis._starkoDebugIds`. The server accepts a UUID in any case, with or
|
|
309
|
+
without hyphens, and answers with the id as it was sent.
|
|
310
|
+
|
|
311
|
+
There are two protocols. The **bulk upload** sends each map straight from
|
|
312
|
+
the build to Starko's storage through a short-lived signed URL; nothing but
|
|
313
|
+
small JSON requests goes through the Starko host. **v1** sends every map
|
|
314
|
+
through the Starko host in parts. The Starko tools use the bulk upload when
|
|
315
|
+
the server has it and v1 otherwise (`uploadProtocol`, `--protocol`).
|
|
316
|
+
|
|
317
|
+
### Bulk upload
|
|
318
|
+
|
|
319
|
+
```
|
|
320
|
+
POST /api/v1/sourcemaps/bulk/check 1,000 chunks a request → the chunks the server lacks
|
|
321
|
+
POST /api/v1/sourcemaps/bulk/start 200 maps a request → per map: a signed upload target, or a status
|
|
322
|
+
PUT <target url> one gzipped map → straight to storage
|
|
323
|
+
POST /api/v1/sourcemaps/bulk/finish 200 maps a request → per map: stored, or what to do next
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The server suggests 2 `bulk/start` or `bulk/finish` requests and 16 PUTs in
|
|
327
|
+
flight (`SOURCEMAP_BULK_REQUEST_CONCURRENCY`, `SOURCEMAP_BULK_UPLOAD_CONCURRENCY`
|
|
328
|
+
in `wire.ts`). More finishes gain nothing: the server verifies one
|
|
329
|
+
workspace's maps at most 6 at a time, and only one of them over 8 MiB
|
|
330
|
+
gzipped (`SOURCEMAP_BULK_VERIFY_PER_WORKSPACE`), across all of that
|
|
331
|
+
workspace's `bulk/finish` and v1 `complete` requests; one finish keeps that
|
|
332
|
+
busy and a second hides the round trip. **Every request may be repeated
|
|
333
|
+
with the same body** after any failure.
|
|
334
|
+
|
|
335
|
+
**How long a request may take.** No route runs longer than its limit on the
|
|
336
|
+
server (`SOURCEMAP_ROUTE_MAX_SECONDS`): `check`, `bulk/check` and
|
|
337
|
+
`bulk/start` 30 s (a start usually answers well within 15 s), v1 `upload`
|
|
338
|
+
and `complete` 60 s, `bulk/finish` 120 s (it starts no verification after
|
|
339
|
+
45 s and finishes those under way: about 70 s at worst). A client waits at
|
|
340
|
+
least that long, plus the network, before it treats a request as lost: the
|
|
341
|
+
Starko tools wait the limit plus 15 s.
|
|
342
|
+
|
|
343
|
+
**1. `bulk/check`** with `{ release?, chunks: [{ chunk_id, content_hash }] }`,
|
|
344
|
+
at most 1,000 chunks, returns `data: { missing: [chunk_id] }`: the chunks
|
|
345
|
+
the server still needs, that is without a stored map and without a map
|
|
346
|
+
pending the server's own verification with the same `content_hash` (unlike
|
|
347
|
+
v1's `check`, which reports a pending map missing). `release` is
|
|
348
|
+
`{ version, commit?, branch? }`; it is created when new. A server that
|
|
349
|
+
predates the bulk upload answers this route with 404 (or 405): use v1.
|
|
350
|
+
|
|
351
|
+
**2. `bulk/start`** with `{ release?, maps: [{ chunk_id, content_hash, size_bytes, file_name? }] }`,
|
|
352
|
+
at most 200 maps. `size_bytes` is the length of the **gzipped** map the
|
|
353
|
+
build will PUT (1 to 67,779,953 bytes, `SOURCEMAP_BULK_MAX_OBJECT_BYTES`).
|
|
354
|
+
It is signed into the URL and storage refuses a body of another length, so
|
|
355
|
+
gzip each map once and send exactly those bytes. `file_name` is the
|
|
356
|
+
bundle's path relative to the build output, at most 512 characters
|
|
357
|
+
(`SOURCEMAP_MAX_FILE_NAME`, counted as JavaScript string length; a longer
|
|
358
|
+
one is a 400, so shorten it first: the Starko tools keep the end of the
|
|
359
|
+
path after a `…`). 200 maps with every field at its limit stay inside the
|
|
360
|
+
1 MiB body limit whatever the characters. A chunk id named twice in one request is answered twice
|
|
361
|
+
when both entries are the same, and refused (400) otherwise. The answer is
|
|
362
|
+
`data: { maps: [...] }`, one entry per map, in request order:
|
|
363
|
+
|
|
364
|
+
| `status` | Meaning | What the build does |
|
|
365
|
+
| --- | --- | --- |
|
|
366
|
+
| `upload` | Reserved; `upload` holds the target (below). Also the answer after a failed map or a PUT that stored nothing: a new object (or a fresh URL for the same one) at once. | PUT the map to it, then name it in `bulk/finish`. |
|
|
367
|
+
| `uploaded` | Already reserved, and storage already holds its object (an earlier PUT landed). No target. | Do not PUT it: name it in `bulk/finish`. |
|
|
368
|
+
| `present` | A stored map with this `content_hash` exists. | Nothing. |
|
|
369
|
+
| `pending` | The same map was uploaded and waits for the server's own verification. | Nothing. |
|
|
370
|
+
| `conflict` | The chunk id has a stored map with another `content_hash` (write-once). | Report it; not retryable. Delete the stored map in Starko to replace it. |
|
|
371
|
+
| `busy` | Only after this chunk id was restarted (new content, failed maps) more than 3 times within about 20 minutes while the earlier URLs may still be used; `retry_after_s` says when one is over (at most about 20 minutes). A normal build never sees it. | Start this map again after `retry_after_s`, or leave it to the next build. |
|
|
372
|
+
| `over_allowance` | The workspace's source-map storage allowance is reached. | Stop: every further map would be refused the same way. Not retryable until maps are deleted. |
|
|
373
|
+
|
|
374
|
+
An entry may carry a `message`. The reservation counts against the
|
|
375
|
+
allowance from this moment. The key's daily byte budget (8 GiB of gzipped
|
|
376
|
+
maps a UTC day) is checked here (what the key stored today plus the
|
|
377
|
+
request's new reservations; a 429 when it would pass) and charged by
|
|
378
|
+
`bulk/finish` for each map it stores, and for each map that fails
|
|
379
|
+
verification (the larger of its size and what it inflated to). A start
|
|
380
|
+
for a map that already has a reservation with the same `content_hash` and
|
|
381
|
+
`size_bytes`, made less than 3 hours ago, re-signs the **same** object (no
|
|
382
|
+
second reservation): that is how an expired URL is renewed, and the answer
|
|
383
|
+
is `uploaded` when storage already holds that object. Anything else (no
|
|
384
|
+
reservation, other content or size, an older reservation, a failed upload)
|
|
385
|
+
reserves a new object at once.
|
|
386
|
+
|
|
387
|
+
The target:
|
|
388
|
+
|
|
389
|
+
```json
|
|
390
|
+
{
|
|
391
|
+
"url": "https://<region>.ingest.uploadthing.com/<key>?expires=…&x-ut-file-size=…&x-ut-acl=private&…&signature=…",
|
|
392
|
+
"method": "PUT",
|
|
393
|
+
"headers": { "Range": "bytes=0-", "x-uploadthing-version": "7.7.4" },
|
|
394
|
+
"form_field": "file",
|
|
395
|
+
"file_name": "sm-5b1f6c0e.bin",
|
|
396
|
+
"content_type": "application/octet-stream",
|
|
397
|
+
"size_bytes": 48213,
|
|
398
|
+
"expires_at": "2026-11-21T10:10:00.000Z",
|
|
399
|
+
"expires_in_s": 599
|
|
400
|
+
}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
`expires_in_s` is the time the URL has left when the server answered, on
|
|
404
|
+
the server's clock; `expires_at` is the same instant as a date. Time the
|
|
405
|
+
expiry from `expires_in_s` and when the answer arrived (a monotonic clock),
|
|
406
|
+
not by comparing `expires_at` with the build machine's clock, which may be
|
|
407
|
+
off. Renew a target that has less than a minute left before its PUT.
|
|
408
|
+
|
|
409
|
+
**3. The PUT.** `PUT <url>` with every header in `headers` and a
|
|
410
|
+
`multipart/form-data` body with exactly one part: name `form_field`,
|
|
411
|
+
filename `file_name`, `Content-Type: content_type`, content the gzipped map
|
|
412
|
+
(exactly `size_bytes` bytes). Nothing else: no `Authorization` (the secret
|
|
413
|
+
key never goes to storage). Any 2xx is success; the answer's body is not
|
|
414
|
+
needed. A PUT that got **no answer** (a network error, a timeout) may be
|
|
415
|
+
repeated to the same target while it is valid. After a **2xx**, never PUT
|
|
416
|
+
that target again: name the map in `bulk/finish`. After a **4xx**, whatever
|
|
417
|
+
it is (an expired URL included), do not PUT that target again either: name
|
|
418
|
+
the map in `bulk/finish`, since an earlier attempt may have stored it;
|
|
419
|
+
`not_uploaded` then means `bulk/start` it again and PUT what that answers.
|
|
420
|
+
Storage is expected to refuse
|
|
421
|
+
a body of another length than `size_bytes` (the server has not verified
|
|
422
|
+
that against its storage provider); `bulk/finish` fails an object of
|
|
423
|
+
another size either way. **The URL is a credential** for that one object:
|
|
424
|
+
never log it or show it, not even on failure. It cannot be revoked: it
|
|
425
|
+
works until `expires_at` (10 minutes after the start, on the server's
|
|
426
|
+
clock), also after the key that got it is revoked. After that, call
|
|
427
|
+
`bulk/start` again for the map. Do not follow a redirect.
|
|
428
|
+
|
|
429
|
+
**A build that cannot reach the storage host** (a proxy or a firewall in
|
|
430
|
+
front of it) sends its maps through v1 instead, the ones it already
|
|
431
|
+
reserved included: v1 takes a reservation over at once when storage holds
|
|
432
|
+
no object for it (see v1 below).
|
|
433
|
+
|
|
434
|
+
**4. `bulk/finish`** with `{ maps: [{ chunk_id, content_hash }] }`, at most
|
|
435
|
+
200 maps: the maps whose PUT succeeded (or may have: finishing a map that
|
|
436
|
+
was not uploaded is harmless). The server reads each object back, checks
|
|
437
|
+
its size, gunzips it, compares its sha256 with `content_hash` and its own
|
|
438
|
+
`debugId` with the chunk id; nothing the build declares is trusted. The
|
|
439
|
+
answer is one entry per map, in request order:
|
|
440
|
+
|
|
441
|
+
| `status` | Meaning | What the build does |
|
|
442
|
+
| --- | --- | --- |
|
|
443
|
+
| `stored` | Verified and stored (also when it already was). | Done. |
|
|
444
|
+
| `pending` | Stored; too large to verify inside the request, the server verifies it in the background. | Done. |
|
|
445
|
+
| `not_uploaded` | Storage has no complete object for the reservation. | `bulk/start` it again (never PUT a target again after a 2xx): it answers `uploaded` once storage shows the object, or a target to PUT. |
|
|
446
|
+
| `not_reserved` | No reservation for this chunk id and `content_hash` (or it was removed). | `bulk/start` again, PUT, finish. |
|
|
447
|
+
| `conflict` | As in `bulk/start`. | Report it; not retryable. |
|
|
448
|
+
| `failed` | The stored object is wrong (size, gzip, sha256, `debugId`, not a source map; `message` says which). Charged to the key's daily budget. | Report it; do not send it again in this build (the same bytes fail again, and each failure costs budget). A fixed build's `bulk/start` reserves a new object at once. |
|
|
449
|
+
| `retry` | Not checked this time (storage did not answer, or the request ran out of time or of its turn at the workspace's verification). | `bulk/finish` again for it. |
|
|
450
|
+
|
|
451
|
+
**423** on any of the three routes (and on v1's `upload`) means the server
|
|
452
|
+
has switched source-map uploads off: its storage served a map without a
|
|
453
|
+
signature. It is not retryable and lasts until a Starko operator fixes
|
|
454
|
+
storage (hours or more): stop uploading and report the message. A
|
|
455
|
+
`bulk/finish` answered 423 deleted the maps it named.
|
|
456
|
+
|
|
457
|
+
Whole-request answers of the three routes:
|
|
458
|
+
|
|
459
|
+
| Status | Meaning | What the build does |
|
|
460
|
+
| --- | --- | --- |
|
|
461
|
+
| 400 | Invalid body (too many entries, a chunk id that is not a UUID, a size out of range, one chunk id with two contents). | Fix the request. |
|
|
462
|
+
| 401 | Missing or invalid key (also one revoked meanwhile). | Stop. |
|
|
463
|
+
| 404, 405 | `bulk/check` on a server without the bulk upload. | Use v1. |
|
|
464
|
+
| 413 | Body over 512 KiB (`bulk/check`) or 1 MiB (`bulk/start`, `bulk/finish`). | Send fewer entries. |
|
|
465
|
+
| 423 | Source-map uploads are disabled, see above. | Stop; do not retry. |
|
|
466
|
+
| 429 | Rate limited (`Retry-After`, at most a minute), too many failed key checks from the address, or (`bulk/start`) the key's daily byte budget (`Retry-After` until the next UTC day). | Wait `Retry-After`; stop when it is hours. |
|
|
467
|
+
| 500 | Unexpected. | Repeat a few times with back-off, then give up. |
|
|
468
|
+
| 503 | `bulk/start`: another start of the workspace is reserving, or the database did not answer. Always with `Retry-After`. | Repeat after `Retry-After` (the Starko tools wait at least that long, five tries). |
|
|
469
|
+
|
|
470
|
+
### v1
|
|
471
|
+
|
|
472
|
+
1. `POST /api/v1/sourcemaps/check` with `{ release?, chunks: [{ chunk_id, content_hash }] }`
|
|
473
|
+
(at most 500 chunks) returns `{ missing: [chunk_id] }`: the maps the server
|
|
474
|
+
still needs.
|
|
475
|
+
2. For each missing map: gzip it, cut it into parts of at most 3 MiB (at most
|
|
476
|
+
32 parts), and send each with
|
|
477
|
+
`POST /api/v1/sourcemaps/upload?chunk_id=…&part=<n>&parts=<total>&content_hash=…`
|
|
478
|
+
(`application/octet-stream`). `part` is 0-based. Parts can be retried and
|
|
479
|
+
sent in any order.
|
|
480
|
+
3. `POST /api/v1/sourcemaps/complete` with `{ chunk_id, parts, content_hash, size_bytes, file_name?, release? }`.
|
|
481
|
+
|
|
482
|
+
A part for a chunk id with an unfinished bulk reservation **takes it over
|
|
483
|
+
at once** when storage holds no object for it (a build that could not reach
|
|
484
|
+
storage falls back to v1); the server keeps the reservation's object key
|
|
485
|
+
until its URL is over, so a PUT that still arrives through it is never lost
|
|
486
|
+
or counted twice. When storage does hold an object for it, or does not
|
|
487
|
+
answer, the part is refused with 409 and a `Retry-After` (up to about 20
|
|
488
|
+
minutes): that upload may still be finished through `bulk/finish`.
|
|
489
|
+
`complete` answers 503 with `Retry-After` while the server is busy verifying
|
|
490
|
+
or storage did not answer: repeat it after that. While the server has
|
|
491
|
+
source-map uploads switched off, `upload` answers 423 (not retryable).
|
|
492
|
+
`file_name` on `complete`: the server keeps the first 512 characters.
|
|
493
|
+
|
|
494
|
+
### Rules the server applies
|
|
495
|
+
|
|
496
|
+
- **A chunk id is write-once.** The first map that completes for a chunk id
|
|
497
|
+
is the one used. A check never reports a chunk that has a completed map as
|
|
498
|
+
missing, and an upload, `complete` or `bulk/start` with a different
|
|
499
|
+
`content_hash` for it is refused (409, or `conflict`). Replacing a map
|
|
500
|
+
means deleting it in Starko first. (The debug id is derived from the
|
|
501
|
+
bundle's bytes, so the same id always means the same bundle and the same
|
|
502
|
+
map.)
|
|
503
|
+
- Before a map is stored, its own `debugId` must equal `chunk_id` and its
|
|
504
|
+
sha256 must equal `content_hash`; otherwise the upload is discarded.
|
|
505
|
+
- A map larger than 64 MiB uncompressed is refused, and a workspace has a
|
|
506
|
+
total storage allowance.
|
|
507
|
+
- Both protocols share the per-key request limit (2,000 requests a minute)
|
|
508
|
+
and the key's daily byte budget (8 GiB a UTC day; maps that fail
|
|
509
|
+
verification count). PUTs to storage are not Starko requests.
|
|
510
|
+
- Uploads and reservations that never complete are removed after a day.
|
|
511
|
+
|
|
512
|
+
## PostHog-compatible ingest
|
|
513
|
+
|
|
514
|
+
Clients whose **servers** run on a stack without a Starko SDK can point one
|
|
515
|
+
of PostHog's **server** SDKs at Starko. Set the SDK's host to
|
|
516
|
+
`{host}/api/ingest/ph` and its project token to the workspace key. In
|
|
517
|
+
browsers, use `@starko-one/sdk`.
|
|
518
|
+
|
|
519
|
+
- Verified: Python (`posthog` 8 and later), .NET (PostHog 2.x; its
|
|
520
|
+
`HostUrl` must end with a slash, `…/api/ingest/ph/`, or it posts to the
|
|
521
|
+
wrong path), Node (`posthog-node` 6).
|
|
522
|
+
- Not supported yet: PHP and Ruby. Their SDKs post to a path ending in a
|
|
523
|
+
slash, which the Starko host answers with a redirect they do not follow;
|
|
524
|
+
Ruby's SDK also drops the path from the host. Use the native route above.
|
|
525
|
+
- Go: not verified.
|
|
526
|
+
|
|
527
|
+
- `POST /batch`, `/capture`, `/e` and `/i/v0/e` accept PostHog's capture
|
|
528
|
+
format (`api_key` + `batch`, or a single event), plain or gzip.
|
|
529
|
+
- Only `$exception` events are kept. Every other event (page views,
|
|
530
|
+
autocapture, identify, …) is discarded when the request is parsed: it is
|
|
531
|
+
never queued, stored or logged.
|
|
532
|
+
- `/flags`, `/decide` and the remote-config paths answer with no flags and
|
|
533
|
+
every optional PostHog feature switched off.
|
|
534
|
+
- The same on/off switch, limits and privacy rules apply as for the native route.
|
|
535
|
+
|
|
536
|
+
Field mapping: `uuid` → `event_id`, `$exception_list` → `exception_list`
|
|
537
|
+
(frame order normalised per SDK and version to most recent call first), `$exception_fingerprint` →
|
|
538
|
+
`fingerprint`, `$exception_level` → `level`, `distinct_id` → `user.id`
|
|
539
|
+
(as text only, see Identity), `$session_id` → `session_id`,
|
|
540
|
+
`$release_id`/`$app_version` → `release`, `$current_url` → `request.url`,
|
|
541
|
+
`$lib` / `$lib_version` → `sdk`. `$ip` and everything else is dropped.
|
|
542
|
+
|
|
543
|
+
## Versions
|
|
544
|
+
|
|
545
|
+
A request with a `v` the server does not support is answered with 400,
|
|
546
|
+
`reason: "unsupported_version"` and `data.supported_versions`. Additions to
|
|
547
|
+
v1 are always optional fields; anything a v1 receiver would reject is v2.
|