WIP: Add docs for virtual folders, bump version to 0.9

docs/api/batch.rst

@@ -21,6 +21,18 @@ and existing files are always overwritten.
 If the filename has a directory part, non-existing directories will be auto-created.
 The path may be either absolute or relative, but only sub-directories under ``/home/work`` is allowed to be created.
 
+.. hint::
+
+   This API is for uploading frequently-changing source files in prior to batch-mode execution.
+   All files uploaded via this API is deleted when the kernel terminates.
+   Use :doc:`virtual folders </api/vfolders>` to store and access larger, persistent,
+   static data and library files for your codes.
+
+.. warning::
+
+   You cannot upload files to mounted virtual folders using this API directly.
+   However, you may copy/move the generated files to virtual folders in your build script or the main program for later uses.
+
 There are several limits on this API:
 
 .. list-table::

docs/api/exec.rst

@@ -97,7 +97,7 @@ Response
        You may use different colors/formatting by the log level when printing the log message.
        This rich logging facilities are available to only supported kernels.
 
-       .. note::
+       .. tip::
 
           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.

docs/api/kernels.rst

@@ -18,26 +18,35 @@ Parameters
 
    * - Parameter
      - Description
+
    * - ``lang``
      - The kernel type, usually the name of one of our supported programming languages.
+
    * - ``clientSessionToken``
      - Client session token. Should be unique for continuous execution (for REPL).
-   * - ``resourceLimits``
-     - An optional argument to specify resource requirements.
+
+   * - ``limits``
+     - An optional object to specify resource requirements.
        Additional charges may apply on the public API service.
        If the requested limits exceeds our internal hard-limits,
        the API may return HTTP 406 "Not acceptable".
 
-       .. list-table::
-          :widths: 20 80
-          :header-rows: 1
+   * - ``limits.maxMem``
+     - Maximum memory to use in KBytes.
+
+   * - ``limits.execTimeout``
+     - Maximum total CPU time in milliseconds.
+
+   * - ``mounts``
+     - An optional list of the name of virtual folders that belongs to the current API key.
+       These virtual folders are mounted under ``/home/work``.
+       For example, if the virtual folder name is ``abc``, you can access it on
+       ``/home/work/abc``.
+
+       If the name contains a colon in the middle, the second part of the string indicates
+       the alias location in the kernel's file system which is relative to ``/home/work``.
 
-          * - Fields
-            - Values
-          * - ``maxMem``
-            - Maximum memory to use in KBytes.
-          * - ``timeout``
-            - Maximum execution timeout in milliseconds.
+       You may mount up to 5 folders for each kernel session.
 
 Example:
 
@@ -46,10 +55,14 @@ Example:
    {
      "lang": "python3",
      "clientSessionToken": "EXAMPLE:STRING",
-     "resourceLimits": {
+     "limits": {
        "maxMem": 51240,
        "timeout": 5000
-     }
+     },
+     "mounts": [
+       "mydata",
+       "mypkgs:.local/lib/python3.6/site-packages"
+     ]
    }
 
 
@@ -93,7 +106,8 @@ Getting kernel information
 * Method: ``GET``
 
 Retrieves information about a kernel session.
-For performance reasons, the returned information may not be real-time; usually they are updated every a few seconds in the server-side.
+For performance reasons, the returned information may not be real-time; usually
+they are updated every a few seconds in the server-side.
 
 Parameters
 """"""""""

docs/api/vfolders.rst

@@ -0,0 +1,174 @@
+Virtual Folders
+===============
+
+Virtual folders provide access to shared, persistent, and reused files across different kernel sessions.
+
+You can mount virtual folders when creating new kernel sessions, and use them
+like a plain directory on the local filesystem.
+Of course, reads/writes to virtual folder contents may have degraded
+performance compared to the main scratch directory (usually ``/home/work`` in
+most kernels) as internally it uses a networked file system.
+
+.. note::
+
+   Currently the total size of a virtual folder is limited to 1 GiB and
+   the number of files is limited to 1,000 files during public beta, but these
+   limits are subject to change in the future.
+
+
+Creating a virtual folder
+-------------------------
+
+* URI: ``/v2/folder/create``
+* Method: ``POST``
+
+Creates a virtual folder associated with the current API key.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+
+   * - ``name``
+     - The human-readable name of the virtual folder.
+       Only ASCII alpha-numeric characters, hyphens, and underscores are allowed.
+       The name must start with alpha-numeric characters.
+
+Example:
+
+.. code-block:: json
+
+   {
+     "name": "mydata",
+   }
+
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 201 Created
+     - The kernel is successfully created.
+   * - 400 Bad Request
+     - The name is malformed or duplicate with your existing
+       virtual folders.
+   * - 406 Not acceptable
+     - You have exceeded internal limits of virtual folders.
+       (e.g., the maximum number of folders you can have.)
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Fields
+     - Values
+   * - ``folderId``
+     - The unique folder ID used for later API calls.
+
+
+Example:
+
+.. code-block:: json
+
+   {
+     "kernelId": "oyU2WOYRYmjCGuKoSkiJ7H2rlN4"
+   }
+
+
+Getting virtual folder information
+----------------------------------
+
+* URI: ``/v2/folder/:id``
+* Method: ``GET``
+
+Retrieves information about a virtual folder.
+For performance reasons, the returned information may not be real-time; usually
+they are updated every a few seconds in the server-side.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``:id``
+     - The virtual folder ID.
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 200 OK
+     - The information is successfully returned.
+   * - 404 Not Found
+     - There is no such folder.
+
+(TODO)
+
+
+Deleting a virtual folder
+-------------------------
+
+* URI: ``/v2/folder/:id``
+* Method: ``DELETE``
+
+This immediately deletes all contents of the given virtual folder and makes the
+folder unavailable for future mounts.
+
+.. danger::
+
+   If there are running kernels that have mounted the deleted virtual folder,
+   those kernels are likely to break!
+
+.. warning::
+
+   There is NO way to get back the contents once this API is invoked.
+
+Parameters
+""""""""""
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``:id``
+     - The virtual folder ID.
+
+Response
+""""""""
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - HTTP Status Code
+     - Description
+   * - 204 No Content
+     - The folder is successfully destroyed.
+   * - 404 Not Found
+     - There is no such folder.
+
+Acessing virtual folders via WebDAV
+-----------------------------------
+
+(TODO)

docs/index.rst

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

requirements.txt

@@ -1,3 +1,3 @@
-sorna-common>=0.7,<0.8
-sorna-manager>=0.7,<0.8
-sorna-agent>=0.7,<0.8
+sorna-common>=0.9,<1.0
+sorna-manager>=0.9,<1.0
+sorna-agent>=0.9,<1.0