A build pipeline uploads each bundle's source map here, so browser errors from minified code show the original file, line and function.
Request
POST /api/v1/ingest/sourcemap
X-Codesafe-Key: <api_key>
Content-Type: application/json
The body names one bundle of one release and carries its map as a JSON string: {release, path, map}. A map may hold 32 MiB.
Example
curl
jq -n --arg release "2.14.1" --arg path "/assets/app.min.js" \
--rawfile map dist/app.min.js.map \
'{release: $release, path: $path, map: $map}' |
curl -X POST https://codesafe.example/api/v1/ingest/sourcemap \
-H "X-Codesafe-Key: $CODESAFE_KEY" \
-H "Content-Type: application/json" \
--data-binary @-JSON
{
"release": "2.14.1",
"path": "/assets/app.min.js",
"map": "{\"version\":3,\"file\":\"app.min.js\",\"sources\":[\"src/checkout.js\"],\"names\":[\"submitOrder\"],\"mappings\":\"AAAA,SAASA\"}"
}Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
release | string | no | printable ASCII, no spaces, ≤ 128 chars | The release the bundle shipped in, as your browser reports name it |
path | string | yes | ≤ 512 chars | The bundle's URL path; a full URL or a bare file name works too |
map | string | yes | ≤ 32 MiB, a Source Map v3 | The map file's content, as one JSON string |
An empty release matches errors sent without one.
Responses
| Status | When | What the client does |
|---|---|---|
202 | Stored: {"success": true, "stored": 1, "replaced": false}; replaced is true when it replaces an earlier upload | Nothing |
400 | Malformed JSON, a release or path codesafe refuses, no map, or a map that is no usable v3 map | Fix the upload; fail the build |
401 | X-Codesafe-Key is missing, or no active project holds it | Fix the key |
405 | The method is not POST | Fix the upload |
413 | The body is over 32 MiB plus 16 KB, or the map is over 16 MiB compressed | Split the bundle |
429 | The project's budget is spent; Retry-After: 60 | Retry once after it |
503 | codesafe cannot store it at the moment | Retry the upload |
Notes
- Upload right after the assets ship, before the release gets traffic.
- A map serves only its exact
release: a map of another version would point at the wrong lines, which is worse than none. - An upload for the same
releaseandpathreplaces the earlier one, so a resend is safe. - A map is checked before it is stored: a broken one fails the build step with
400instead of resolving nothing. - Maps resolve browser errors only (
runtime: "browser"), from the next event on.
What resolving changes
The top frame and up to 20 stack lines are rewritten, and each keeps its minified place:
at submitOrder (src/checkout.js:42:9) [was app.min.js:1:48211]
When the map embeds sourcesContent, the original source around the line shows under the error, as a server sender's code block does.
How path is filed
A full URL is reduced to its path and a query string is dropped. A path is filed in one spelling: repeated slashes collapsed, . and .. resolved, unreserved %XX decoded. A bare file name matches any bundle of that name.
What a usable map is
A JSON object with version: 3, a mappings string and a sources array. An index map, which holds sections instead of mappings, is refused: upload each bundle's own map.
Without an upload
When an error names a bundle with no uploaded map, codesafe follows the bundle's //# sourceMappingURL= once, inline data: maps included. The bundle must be on one of the project's ALLOWED ORIGINS and on a public address, at most 4 MiB, its map at most 32 MiB; a project fetches at most 60 an hour and keeps its 24 newest fetched maps. Uploading is the reliable path.
How many maps are kept
A project keeps 240 maps; past that, the ones untouched the longest go first. A project's maps are parsed at most 120 times an hour; past that, its errors keep their minified stacks until the hour turns.