Update docs for v2 API and add batch-mode API.

docs/_static/custom.css

@@ -33,3 +33,18 @@ code, .code, .pre, tt {
     font-family: Menlo, Monaco, Consolas, "DejaVu Sans Mono", "Roboto Mono", "Bitstream Vera Sans Mono", monospace !important;
     font-size: 12px !important;
 }
+
+.rst-content ul, .rst-content ol {
+    line-height: inherit !important;
+    margin-top: 8px !important;
+    margin-bottom: 8px !important;
+}
+
+.rst-content li {
+    margin-bottom: 3px !important;
+}
+
+.admonition p, .admonition div {
+    line-height: 1.2;
+    margin-bottom: 12px;
+}

docs/api/auth.rst

@@ -120,11 +120,11 @@ The success example in `Example Requests and Responses`_ makes a string to sign
 .. code-block:: text
 
    GET
-   /v1
+   /v2
    20160930T01:23:45Z
    host:your.sorna.api.endpoint
    content-type:application/json
-   x-sorna-version:v1.20160915
+   x-sorna-version:v2.20170215
    e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
 
 In this example, the hash value  ``e3b0c4...`` is generated from an empty string using the SHA256 hash function since there is no body for GET requests.
@@ -135,7 +135,7 @@ Then, the client should calculate the signature using the derived signing key an
 
    import hashlib, hmac
 
-   str_to_sign = 'GET\n/v1...'
+   str_to_sign = 'GET\n/v2...'
    sign_key = get_sign_key()  # see "Generating a signing key"
    m = hmac.new(sign_key, str_to_sign.encode('utf8'), hashlib.sha256)
    signature = m.hexdigest()
@@ -164,12 +164,12 @@ Success example for checking the latest API version
 
 .. code-block:: text
 
-   GET /v1 HTTP/1.1
+   GET /v2 HTTP/1.1
    Host: your.sorna.api.endpoint
    Date: 20160930T01:23:45Z
    Authorization: Sorna signMethod=HMAC-SHA256, credential=AKIAIOSFODNN7EXAMPLE:022ae894b4ecce097bea6eca9a97c41cd17e8aff545800cd696112cc387059cf
    Content-Type: application/json
-   X-Sorna-Version: v1.20160915
+   X-Sorna-Version: v2.20170215
 
 .. code-block:: text
 
@@ -182,7 +182,7 @@ Success example for checking the latest API version
    X-RateLimit-Reset: 897065
 
    {
-      "version": "v1.20160915"
+      "version": "v2.20170215"
    }
 
 
@@ -191,11 +191,11 @@ Failure example with a missing authorization header
 
 .. code-block:: text
 
-   GET /v1/kernel/create HTTP/1.1
+   GET /v2/kernel/create HTTP/1.1
    Host: your.sorna.api.endpoint
    Content-Type: application/json
    X-Sorna-Date: 20160930T01:23:45Z
-   X-Sorna-Version: v1.20160915
+   X-Sorna-Version: v2.20170215
 
 .. code-block:: text
 

docs/api/batch.rst

@@ -0,0 +1,162 @@
+Code Execution (Batch Mode)
+===========================
+
+Some kernels provide the batch mode, which offers an explicit build step
+required for multi-module programs or compiled programming languages.
+In this mode, you first upload files in prior to execution.
+
+Uploading files
+---------------
+
+* URI: ``/v2/kernel/:id/upload``
+* Method: ``POST``
+
+Upload files to the kernel session.
+You may upload multiple files at once using multi-part MIME encoding in the request body.
+The uploaded files are placed under ``/home/work`` directory (which is the home directory for all kernels by default),
+and existing files are always overwritten.
+
+Executing
+---------
+
+* URI: ``/v2/kernel/:id``
+* Method: ``POST``
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``:id``
+     - The kernel ID.
+   * - ``type``
+     - A constant string ``"batch"``.
+
+   * - ``options.build``
+
+     - The bash command to build the main program from the given uploaded files.
+
+       If this field is not present, an empty string or ``null``, it skips the build step.
+
+       If this field is a constant string ``"*"``, it will use a default build script provided
+       by the kernel.
+       For example, the C kernel's default Makefile adds all C source files
+       under the working directory and copmiles them into ``./main``
+       executable, with commonly used C/link flags: ``"-pthread -lm -lrt -ldl"``.
+
+   * - ``options.buildLog``
+
+     - A boolean that indicates whether to separately report the logs from the build step.
+       (default: ``false``)
+
+       If set ``false``, all console outputs during the build step
+       are swallowed silently and only the console outputs from the main
+       program are returned.
+       This looks like you only run the main program with a hidden build step.
+
+       However, if the build command fails with a non-zero exit code, then the
+       ``"finished"`` response contains the swallowed console outputs of the
+       build command.  You can distinguish failures from the build step and the
+       execution step using ``result.options.step`` value.
+
+       If set ``true``, at least one ``"continued"`` response will be generated
+       to explicitly report the console outputs from the build step.
+       Like the execution step, there may be mulitple ``"continued"`` responses
+       with ``result.options.exitCode`` set ``null`` when the build step takes
+       long time.
+
+   * - ``options.exec``
+
+     - The bash command to execute the main program.
+
+       If this is not present, an empty string, or ``null``, the server only
+       performs the build step and ``options.buildLog`` is assumed to be
+       ``true`` (the given value is ignored).
+
+.. note::
+
+   All shell commands are by default executed under ``/home/work``.
+   The common environment is:
+
+   .. code-block:: text
+
+      TERM=xterm
+      LANG=en_US.UTF-8
+      SHELL=/bin/bash
+      USER=work
+      HOME=/home/work
+
+   but individual kernels may have additional environment settings.
+
+.. warning::
+
+   The shell does NOT have access to sudo or the root privilege.
+   Though, some kernels may allow installation of language-specific packages in
+   the user directory.
+
+   Also, your build script and the main program is executed inside
+   Sorna Jail, meaning that some system calls are blocked by our policy.
+   Since ``ptrace`` syscall is blocked, you cannot use native debuggers
+   such as gdb.
+
+   This limitation, however, is subject to change in the future.
+
+Example:
+
+.. code-block:: json
+
+   {
+     "type": "batch",
+     "options": {
+       "build": "gcc -Wall main.c -o main -lrt -lz",
+       "exec": "./main"
+     }
+   }
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - The kernel has responded with the execution result.
+       The response body contains a JSON object as described below.
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Fields
+     - Values
+   * - ``result.status``
+
+     - One of ``"continued"``, ``"waiting-input"``, or ``"finished"``, like the query mode.
+       Please refer :doc:`the query mode documentation </api/exec>`
+       for their meanings and how you should handle them.
+
+       Even when this is ``"continued"``, you may notice if the build step is
+       finished by checking that ``result.options.exitCode`` is *not* ``null``
+       and ``result.options.step`` is ``"build"``.
+
+   * - ``result.console``
+
+     - Refer :doc:`the query mode documentation </api/exec>`.
+
+   * - ``result.options``
+
+     - Refer :doc:`the query mode documentation </api/exec>`.
+       In the batch mode, it always has at least the following fields:
+
+       * ``exitCode``: An integer whose value is the exit code of the build command or the main command.
+         Until the process for the current step exits, this field is ``null``.
+       * ``step``: Which step it generated this response. Either ``"build"`` or ``"exec"``.
+         It is useful when you wish to separately display the console outputs from the different steps.
+

docs/api/convention.rst

@@ -24,12 +24,12 @@ A version string of the Sorna API uses two parts: a major revision (prefixed wit
 For example, ``v23.20250101`` indicates a 23rd major revision with a minor release at January 1st in 2025.
 
 We keep backward compatibility between minor releases within the same major version.
-Therefore, all API query URLs are prefixed with the major revision, such as ``/v1/kernel/create``.
+Therefore, all API query URLs are prefixed with the major revision, such as ``/v2/kernel/create``.
 Minor releases may introduce new parameters and response fields but no URL changes.
 Accessing unsupported major revision returns HTTP 404 Not Found.
 
 A client must specify the API version in the HTTP request header named ``X-Sorna-Version``.
-To check the latest minor release date of a specific major revision, try a GET query to the URL with only the major revision part (e.g., ``/v1``).
+To check the latest minor release date of a specific major revision, try a GET query to the URL with only the major revision part (e.g., ``/v2``).
 The API server will return a JSON string in the response body containing the full version.
 When querying the API version, you do not have to specify the authorization header and the rate-limiting is enforced per the client IP address.
 Check out more details about :doc:`auth` and :doc:`ratelimit`.
@@ -39,5 +39,5 @@ Example version check response body:
 .. code-block:: json
 
    {
-      "version": "v1.20160915"
+      "version": "v2.20170215"
    }

docs/api/exec.rst

@@ -4,7 +4,7 @@ Code Execution (Query Mode)
 Executing a user code snippet
 -----------------------------
 
-* URI: ``/v1/kernel/:id``
+* URI: ``/v2/kernel/:id``
 * Method: ``POST``
 
 Executes a snippet of user code using the specified kernel session.
@@ -24,8 +24,8 @@ Parameters
      - Description
    * - ``:id``
      - The kernel ID.
-   * - ``codeId``
-     - A unique identifier of the given code.  Currently, the API server ignores it.
+   * - ``type``
+     - A constant string ``"query"``.
    * - ``code``
      - A string of user-written code.  All non-ASCII data must be encoded in UTF-8 or any format acceptable by the kernel.
 
@@ -34,7 +34,7 @@ Example:
 .. code-block:: json
 
    {
-     "codeId": "ea24bba4-5499-4f4c-bdbd-c475cf019bfe",
+     "type": "query",
      "code": "print('Hello, world!')"
    }
 
@@ -60,7 +60,7 @@ Response
      - Values
    * - ``result.status``
 
-     - One of ``"finished"``, ``"continued"``, ``"waiting-input"``.
+     - One of ``"continued"``, ``"waiting-input"``, ``"finished"``.
 
        If this is ``"continued"``, you should repeat making another API call until you get ``"finished"`` status.
        This happens when the user code runs longer than a few seconds, to allow the client to show its progress.
@@ -99,7 +99,8 @@ Response
 
        .. note::
 
-          All returned strings are *not* escaped. You should take care of this as well as formatting new lines properly (use ``<pre>`` element or replace them with ``<br>``) when rendering the result to web browsers.
+          All returned strings are *not* escaped. You should take care of this as well as formatting new lines properly
+          (use ``<pre>`` element or replace them with ``<br>``) when rendering the result to web browsers.
           An easy way to do this safely is to use ``insertAdjacentText()`` DOM API.
 
    * - ``result.options``

docs/api/kernels.rst

@@ -4,7 +4,7 @@ Kernel Management
 Creating a kernel session
 -------------------------
 
-* URI: ``/v1/kernel/create``
+* URI: ``/v2/kernel/create``
 * Method: ``POST``
 
 Creates a kernel session to run user-input code snippets.
@@ -89,7 +89,7 @@ Example:
 Getting kernel information
 --------------------------
 
-* URI: ``/v1/kernel/:id``
+* URI: ``/v2/kernel/:id``
 * Method: ``GET``
 
 Retrieves information about a kernel session.
@@ -170,7 +170,7 @@ Example:
 Destroying a kernel session
 ---------------------------
 
-* URI: ``/v1/kernel/:id``
+* URI: ``/v2/kernel/:id``
 * Method: ``DELETE``
 
 Terminates a kernel session.
@@ -205,7 +205,7 @@ Response
 Restarting a kernel session
 ---------------------------
 
-* URI: ``/v1/kernel/:id``
+* URI: ``/v2/kernel/:id``
 * Method: ``PATCH``
 
 Restarts a kernel session.

docs/api/stream.rst

@@ -7,7 +7,7 @@ The streaming mode provides a direct web-based terminal access to kernel contain
 Terminal Emulation
 ------------------
 
-* URI: ``/v1/stream/kernel/:id/pty``
+* URI: ``/v2/stream/kernel/:id/pty``
 * Method: GET upgraded to WebSockets
 
 This endpoint provides a duplex continuous stream of JSON objects via the native WebSocket.
@@ -129,7 +129,7 @@ Server-side errors
 Monitoring events from the kernel session
 -----------------------------------------
 
-* URI: ``/v1/stream/kernel/:id/events``
+* URI: ``/v2/stream/kernel/:id/events``
 * Method: GET upgraded to WebSockets
 
 This API function is read-only --- meaning that you cannot send any data to this URI.

docs/index.rst

@@ -56,6 +56,7 @@ Table of Contents
    api/kernels
    api/exec
    api/stream
+   api/batch
 
 .. _dev: