JetStream URI Scheme
####################

Overview
========

JetStream Clients can be controlled using a ``jetstream:`` URI scheme. Any JetStream URIs should conform to `RFC 3986`_.

The JetStream URI is defined as ``jetstream://authority/action/path?query#anchor``:


.. glossary::

   :index:`authority <pair: jetstream uri; authority>`
       When addressing a specific server, *authority* can be expressed as a hostname, ip, and optional port number, referring to the JetStream server and API port. If port number is not specified, JetStream default 8886 is assumed. The address and port must be specified as defined in `Section 3.2 of RFC 3986`_. Please note that JetStream Clients will ignore the user infomration portion of the URI.

         Example:

           * jetstream://example.com/
           * jetstream://example.com:8886/
           * jetstream://1.2.3.4/
           * jetstream://1.2.3.4:8887/

       When the *authority* is left blank, the recipient of the action is the JetStream client itself, and must start with three slashes (``///``).

         For example

           * jetstream:///


   :index:`action <pair: jetstream uri; action>`
       Action defines the task the JetStream client should do. The action can optionally be slash (``/``) terminated.

         Example:

           * jetstream://example.com/connect
           * jetstream://example.com/connect/


   :index:`path <pair: jetstream uri; path>`
       Unused, and reserved for future use.


   :index:`query <pair: jetstream uri; query>`
       Percent-encoded key=value pairs, separated by ampersand (``&``). Actions may require specific key-value pairs to be present.

          Example:

             * jetstream://example.com/action?key1=value1&key2=value2
             * jetstream://example.com/download?token=TO.K.EN



   :index:`anchor <pair: jetstream uri; anchor>`
      Unused, and reserved for future use.

.. _RFC 3986: https://tools.ietf.org/html/rfc3986
.. _Section 3.2 of RFC 3986: https://tools.ietf.org/html/rfc3986#section-3.2


Supported Actions
=================

.. glossary::

   :index:`connect <triple: jetstream uri; action; connect>`
      Connect to the server specified in *authority*. The *authority* section must not be blank.

      For example, ``jetstream://example.com/connect`` would cause a client to start up and automatically connect to the *example.com* JetStream server on port 8886 (default).

      .. seealso::
         - :ref:`jetstream-client:send__send_current_location#connecting`

   :index:`download <triple: jetstream uri; action; download>`
      Connect to the JetStream server specified in *authority*, and initiate download of shared link specified by the ``token`` key-value pair given in *query*. The *authority* section must not be blank.

      For example, ``jetstream://example.com/download?token=TO.K.EN``, would cause the JetStream Client to connect to *example.com* and attempt to download a shared link identified by token ``TO.K.EN``.

      .. seealso::
         - :doc:`/using_jetstream/shared_links`
         - :doc:`jetstream-client:transfers/transfer-download-shared-files`

   :index:`open <triple: jetstream uri; action; open>`
      Connect to the JetStream server specified in *authority*, and log in using the ``token`` key-value pair given in *query*. The *authority* section must not be blank.

      For example, ``jetstream://example.com/open?token=TO.K.EN``, would cause the JetStream Client to connect to *example.com* and log in with the API token identified by token ``TO.K.EN``.

      .. seealso::
         - :doc:`/using_jetstream/api_tokens`
         - :doc:`jetstream-client:transfers/transfer-connect-to-shared-folder`

Example Uses
============

The JetStream URI schema can be used to simplify 3rd party client setup by directing users to a web address redirection, which will prompt the user to start the JetStream Client application, and connect to the given server.

.. _jetstream_uri#simple_redirect_setup:

Simple Redirect Setup
---------------------

Let's assume an organization has a website at *http://example.com*, and we want our users to connect to *jetstream.example.com* JetStream server.

The web server administrator could setup the web server to redirect *http://example.com/jetstream-connect* to *jetstream://jetstream.example.com/connect*. We can then email this HTTP link to the organization's users. When a user, who already has a JetStream Client installed, browses to the *http://example.com/jetstream-connect* link, the JetStream Client will pop up and connect to the *jetstream.example.com* server automatically. For first-time connections, the user will be prompted for username and password.

Unfortunately, users without a JetStream Client won't be notified in any way. For a more universal solution, see the :ref:`jetstream_uri#file_redirect_setup` below.

.. _jetstream_uri#file_redirect_setup:

File Redirect Setup
-------------------

Expanding on the :ref:`jetstream_uri#simple_redirect_setup` example above, the web server administrator could publish a simple html file, that will handle the redirection. Let's assume the following file is published at *http://example.com/jetstream-connect.html*.

.. code-block:: html

   <html>
      <head>
         <meta http-equiv="refresh" content="1; URL=jetstream://jetstream.example.com/connect" />
         <title>Connecting to jetstream.example.com</title>
      </head>
      <body>
         <h1>Connecting to jetstream.example.com</h1>
         <p>You will be prompted to open the JetStream Client application momentarily. If you're connecting for the first time, you will be prompted for username and password once JetStream Client starts.</p>
         <p>If you don't have the JetStream Client, please <a href="https://gojetstream.io/downloads" target="_blank">download</a> it first. You can then attempt to <a href="jetstream://jetstream.example.com/connect">connect again</a></p>
      </body>
   </html>

If a user that already has a JetStream client browses to this link, the JetStream client application will pop up and behave as it did in the previous example. Users that do not have JetStream client installed will see a page with download instructions, and ability to connect to the server once they've installed the Jetsream Client.
