docs: Add symbolicate-js endpoint documentation

docs/api/index.md

@@ -5,13 +5,14 @@ title: Overview
 # API
 
 Symbolicator exposes a HTTP API to allow symbolication of raw native stack
-traces and minidumps. All information necessary for symbolication needs to be
-part of the request, such as external buckets and their auth tokens or full
-stack traces. There are the following endpoints:
+traces, minidumps, and JavaScript stack traces. All information necessary for symbolication
+needs to be part of the request, such as external buckets and their auth tokens
+or full stack traces. There are the following endpoints:
 
 - `POST /symbolicate`: Symbolicate raw native stacktrace
 - `POST /minidump`: Symbolicate a minidump and extract information
 - `POST /applecrashreport`: Symbolicate an Apple Crash Report
+- `POST /symbolicate-js`: Symbolicate JavaScript stacktrace
 - `GET /requests/:id`: Status update on running symbolication jobs
 - `GET /healthcheck`: System status and health monitoring
 

docs/api/response.md

@@ -4,7 +4,9 @@ title: Symbolication Response
 
 # Symbolication Response
 
-The response to a symbolication request is a JSON object which contains
+## Native Response
+
+The response to a native symbolication request is a JSON object which contains
 different data depending on the status of the symbolication job:
 
 - `pending`: Symbolication has not finished yet; try again later. This is only
@@ -14,7 +16,7 @@ different data depending on the status of the symbolication job:
 - `error`: Something went wrong during symbolication, and details are in the
   payload.
 
-## Success Response
+### Success Response
 
 Symbol server responds with _200 OK_ and the response payload listed below if
 symbolication succeeds within a configured timeframe (around 20 seconds):
@@ -73,7 +75,7 @@ occurred during symbolication, such as missing symbol files or unresolvable
 addresses within symbols are reported as values for `status` in both modules and
 frames.
 
-## Note on Addresses
+### Note on Addresses
 
 Addresses (`instruction_addr` and `sym_addr`) can come in two versions. They
 can be absolute or relative. Symbolicator will always try to make addresses
@@ -82,7 +84,7 @@ not have absolute addresses in which case the addresses stay relative. This is
 identified by the `addr_mode` property. When it's set to `"abs"` it means
 the addresses are absolute, when `"rel:X"` it's relative to module index `X`.
 
-## Backoff Response
+### Backoff Response
 
 If symbolication takes longer than the threshold `timeout`, the server instead
 responds with a backoff response. It will then continue to fetch symbols and
@@ -105,7 +107,7 @@ guarantee. The request may be repeated at any time:
 
     GET /requests/deadbeef?timeout=123
 
-## Invalid Request Response
+### Invalid Request Response
 
 If the user provided a non-existent request ID, the server responds with _404
 Not Found_.
@@ -115,3 +117,71 @@ deploy. Clients must expect that 404 is returned even for valid request IDs and
 then re-schedule symbolication
 
 On a related note, state on the server is generally ephemeral.
+
+
+## JavaScript Response
+
+The response to a JavaScript symbolication request is a JSON object which contains
+a list of original raw stack traces, corresponding list of processed stack traces
+and an optional list of errors that happened during symbolication.
+
+```javascript
+{
+  "stacktraces": [
+    {
+      "frames": [
+        {
+          "function": "onFailure",
+          "filename": "test.js",
+          "module": "files/test",
+          "abs_path": "http://localhost:<port>/files/test.js",
+          "lineno": 5,
+          "colno": 11,
+          "pre_context": [
+            "var makeAFailure = (function() {",
+            "  function onSuccess(data) {}",
+            "",
+            "  function onFailure(data) {"
+          ],
+          "context_line": "    throw new Error('failed!');",
+          "post_context": [
+            "  }",
+            "",
+            "  function invoke(data) {",
+            "    var cb = null;",
+            "    if (data.failed) {"
+          ],
+          "data": {
+            "sourcemap": "http://localhost:<port>/files/app.js.map"
+          }
+        }
+      ]
+    }
+  ],
+  "raw_stacktraces": [
+    {
+      "frames": [
+        {
+          "abs_path": "http://localhost:<port>/files/app.js",
+          "lineno": 1,
+          "colno": 64,
+          "context_line": "var makeAFailure=function(){function n(n){}function e(n){throw new Error(\"failed!\")}function r(r){var i=null;if(r.failed){i=e}else{i=n}i(r)} {snip}",
+          "post_context": [
+            "",
+            "",
+            "//# sourceMappingURL=a.different.map",
+            "",
+            "//@ sourceMappingURL=another.different.map"
+          ]
+        }
+      ]
+    }
+  ],
+  "errors": [
+    {
+      "abs_path": "http://localhost:<port>/assets/missing_bar.js",
+      "type": "missing_source"
+    }
+  ]
+}
+```

docs/api/sourcemaps.md

@@ -0,0 +1,87 @@
+---
+title: POST /symbolicate-js
+---
+
+# Symbolication Request
+
+```http
+POST /symbolicate-js?timeout=123&scope=123 HTTP/1.1
+Content-Type: application/json
+
+{
+  "source": {
+    "id": "<id>",
+    "url": "https://sentry.io/api/0/projects/sentry-org/sentry-project/artifact-lookup/",
+    "token": "secret"
+  },
+  "stacktraces": [
+    {
+      "frames": [
+        {
+          "function": "x",
+          "module": "x",
+          "filename": "x",
+          "abs_path": "x",
+          "lineno": 1,
+          "colno": 1,
+          "in_app": true
+        }
+      ]
+    }
+  ],
+  "modules": [
+    {
+      "code_file": "some-code-file",
+      "debug_id": "some-debug-id",
+      "type": "debug_id"
+    }
+  ],
+  "dist": "production",
+  "release": "1.33.1",
+  "scraping": {
+    "enabled": true,
+    "allowed_origins": ["*.domain.com"]
+  }
+}
+```
+
+## Query Parameters
+
+- `timeout`: If given, a response status of `pending` might be sent by the
+  server.
+- `scope`: An optional scope which will be used to isolate cached files from
+  each other
+
+## Request Body
+
+    pub scraping: ScrapingConfig,
+    pub options: JsRequestOptions,
+
+A JSON payload describing the stack traces and code modules for symbolication,
+as well as configuration for scraping sources from external servers:
+
+- `source`: A descriptors for Sentry source to be used for symbolication. See
+  [Sentry](index.md) source.
+- `modules`: A list of source code files with a corresponding debug id that
+  were loaded during JS code execution. The list is handled by the Sentry source.
+- `stacktrace`: A list of stacktraces to symbolicate.
+  - `frames`: A list of frames with corresponding `abs_path`, `lineno`,
+    and `colno`, as well as minified `function` name.
+- `release`: Name of Sentry `release` for the processed request.
+- `dist`: Name of Sentry `dist` for the processed request.
+- `scraping`: Configuration for scraping of JS sources and sourcemaps from the web.
+  - `enabled`: Whether scraping should happen at all.
+  - `allowed_origins`: A list of "allowed origin patterns" that control what
+    URLs we are allowed to scrape from. Allowed origins may be defined in several ways:
+    - `http://domain.com[:port]`: Exact match for base URI (must include port).
+    - `*`: Allow any domain.
+    - `*.domain.com`: Matches domain.com and all subdomains, on any port.
+    - `domain.com`: Matches domain.com on any port.
+    - `*:port`: Wildcard on hostname, but explicit match on port.
+  - `headers`: A map of headers to send with every HTTP request while scraping.
+- `options`: Symbolication-specific options which control the endpoint's behavior.
+  - `apply_source_context`: Whether to apply source context for the stack frames.
+
+## Response
+
+See [Symbolication Response](response.md).

docs/index.md

@@ -8,8 +8,8 @@ title: Introduction
 </p>
 
 Symbolicator is a standalone service that resolves function names, file location
-and source context in native stack traces. It can process Minidumps and Apple
-Crash Reports. Additionally, Symbolicator can act as a proxy to symbol servers
+and source context in Native and JavaScript stack traces. It can process Minidumps, Apple
+Crash Reports and Source Maps. Additionally, Symbolicator can act as a proxy to symbol servers
 supporting multiple formats, such as Microsoft's symbol server or Breakpad
 symbol repositories.
 

mkdocs.yml

@@ -25,5 +25,6 @@ nav:
     - api/minidump.md
     - api/symbolication.md
     - api/applecrashreport.md
+    - api/sourcemaps.md
     - api/response.md
     - api/proxy.md