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:

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:///

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/

path

Unused, and reserved for future use.

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

anchor

Unused, and reserved for future use.

Supported Actions¶

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).

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.

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 File Redirect Setup below.

File Redirect Setup¶

Expanding on the 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.

<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://jetstream.cumul8.com/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.