DOCUMENTATION

Source maps

Upload a bundle's map, and browser stacks read as source.

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

FieldTypeRequiredLimitWhat it does
releasestringnoprintable ASCII, no spaces, ≤ 128 charsThe release the bundle shipped in, as your browser reports name it
pathstringyes≤ 512 charsThe bundle's URL path; a full URL or a bare file name works too
mapstringyes≤ 32 MiB, a Source Map v3The map file's content, as one JSON string

An empty release matches errors sent without one.

Responses

StatusWhenWhat the client does
202Stored: {"success": true, "stored": 1, "replaced": false}; replaced is true when it replaces an earlier uploadNothing
400Malformed JSON, a release or path codesafe refuses, no map, or a map that is no usable v3 mapFix the upload; fail the build
401X-Codesafe-Key is missing, or no active project holds itFix the key
405The method is not POSTFix the upload
413The body is over 32 MiB plus 16 KB, or the map is over 16 MiB compressedSplit the bundle
429The project's budget is spent; Retry-After: 60Retry once after it
503codesafe cannot store it at the momentRetry 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 release and path replaces the earlier one, so a resend is safe.
  • A map is checked before it is stored: a broken one fails the build step with 400 instead 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.