SPECS.md

Lantern state document and transport protocol specifications

Draft 0.0.1

Status: incomplete

Introduction

Lantern's user interface is implemented as a web application, rendered inside a browser embedded inside a native desktop application. This document describes the specifications for the representation of the state the web frontend expects to receive from the backend to be able to display a correctly behaving user interface, the protocol for sending the state and updates to it, and the http API the frontend expects to be able to call to notify the backend of user interactions.

State transport protocol

Lantern's bayeux server is responsible for sending state updates to the frontend in real time as JSON messages. When the Lantern UI is open, a bidirectional, real-time connection to the bayeux server is made via JavaScript. Before the connection has been established, or in case it is ever lost, the frontend should indicate it's trying to connect to the Lantern backend and block any user interaction until the connection is established. The bayeux client takes care of automatically attempting to reconnect to the bayeux server if the connection is lost.

Subscription

Upon successful connection to the bayeux server, the frontend will request subscription to a channel named /sync. This is the channel over which the frontend receives updates to its (initially empty) model object from the backend.

State updates

When the bayeux server honors a client's subscription request to the /sync channel, it should immediately publish a JSON PATCH to the channel with the necessary state to populate the model:

[{
  "op": "replace",
  "path": "",
  "value": {
    "system": {
      "os": "...",
      ...
    },
    ...
  }
}]

After initial state is published in full, updates to the state can likewise be published using JSON PATCH, e.g.

[{
  "op": "add",
  "path": "/friends/-",
  "value": {
    "email": "user@example.com",
    "status": "pending"
  }
},{
  "op": "replace",
  "path": "/friends/-/status",
  "value": "friend"
}]

---

State document specification

Every possible state determining the frontend's behavior can be represented within the following state document, corresponding to the model object which the backend maintains on the frontend through comet publications:

mock object	scenarios object set of available scenarios the mock backend can simulate for testing The mock field should only be sent by the mock backend.
dev boolean	Whether the backend is in development mode.
system object	os "windows" | "osx" | "ubuntu" operating system version "10.7.5" | "12.04" | ... os version arch "x86" | "x86_64" | ... architecture processor "1.8 GHz Intel Core i7" | ... processor memory "4 GB 1333 MHz DDR3" | ... memory bytesFree int available bytes on the disk Lantern writes to graphics "Intel HD Graphics 3000 384 MB" | ... graphics displays [[1280, 1024]] | ... list of [pixel width, pixel height] pairs for each display java "1.7.0_33" | ... java version chrome "25.0.1364.5" | ... chrome version lang "en" | "es" | ... The system's language setting as a two-letter ISO 639-1 code. Determines the language the UI is displayed in when the user's lang setting (under settings below) is not available (e.g. not yet set or settings are locked).
location object	country ISO 3166-1 alpha-2 country code (last known) country connecting from (as reported by geoip lookup) lat float (last known) latitude connecting from (as reported by geoip lookup) lon float (last known) longitude connecting from (as reported by geoip lookup)
countries object	<COUNTRY-CODE> "AD" | "AE" | "AF" | ... censors boolean whether this country employs pervasive censorship, as reported by <LIVE SOURCE WHICH IS KEPT UP-TO-DATE> # XXX TODO bps int Total number of bytes per second being transferred right now by all online peers in this country. bytesEver int Total number of bytes ever transferred by peers in this country. nusers object online int Number of users online now in this country. ever int Number of users that ever connected in this country. npeers object online object give int Number of Give Mode peers online now in this country. get int Number of Get Mode peers online now in this country. giveGet int Number of Give and Get Mode peers online now in this country. ever object give int Number of Give Mode peers ever to connect in this country. get int Number of Get Mode peers ever to connect in this country. giveGet int Number of Give and Get Mode users ever to connect in this country.
global object	nusers object online int Total number of users online now worldwide. ever int Total number of users ever worldwide. npeers object online object give int Number of Give Mode peers online now worldwide. get int Number of Get Mode peers online now worldwide. giveGet int Number of Give and Get Mode peers online now worldwide. ever object give int Number of Give Mode peers ever to connect worldwide. get int Number of Get Mode peers ever to connect worldwide. giveGet int Number of Give and Get Mode users ever to connect worldwide. bps int Total bytes per second being transferred worldwide right now. bytesEver int Total bytes transferred worldwide ever.
version object	installed object major int major version of the currently-running Lantern instance minor int minor version of the currently-running Lantern instance patch int patch version of the currently-running Lantern instance tag string tag version of the currently-running Lantern instance git string git revision of the currently-running Lantern instance releaseDate date e.g. "2012-12-12" release date of the currently-running Lantern instance installerUrl url installer url for the user's platform api object The version of the API the backend conforms to (where API refers to the state document schema, update protocol, and http API taken as a whole) major int api major version minor int api minor version patch int api patch version The UI should display an 'unexpected state' error if its required api version is incompatible with the version published by the backend according to semantic versioning (different major or minor) latest object as inversion.installed, but referring to the latest released version of Lantern rather than the currently-running version. Does not need the "api" field, but should add an "installerSHA1" field corresponding to the SHA-1 of the installer at installerUrl, and an "infoUrl" field pointing to a url with more info about changes in this version. updateAvailable boolean Whether the latest available version of Lantern is newer than the currently-running version. The UI should prompt to update when true.
notifications object	Hash of {notificationid: notificationObject} mappings the frontend should display to the user. A notificationid key is the unique id of the notification object it maps to. Notification objects look like: autoClose int How many seconds the frontend should wait before automatically sending an /interaction/close request for this alert. A value of 0 means never auto close. /interaction/close requests contain a JSON request body like {"notification": notificationid}. Automatically generated /interaction/close requests will additionally pass an "auto": true parameter in the JSON body. Auto-close requests for already-closed notifications should be ignored. type "info" | "warning" | "important" | "error" | "success" controls how the UI should display the alert message string Message to display. May contain html; unsafe elements will be sanitized. Message strings are expected to be translated into the user's chosen language.
modal "settingsLoadFailure" | "welcome" | "giveModeForbidden" | "authorize" | "connecting" | "contact" | "settings" | "about" | "updateAvailable" "notInvited" | "proxiedSites" | "lanternFriends" | "finished" | ""	Instructs the UI to display the corresponding modal dialog. A value of empty string means no modal dialog should be displayed.
setupComplete boolean	Whether the user has completed Lantern setup
connectivity object	internet boolean Whether the system has internet connectivity ip string The system's public IP address, if available gtalkAuthorized boolean Whether the user has authorized Lantern via Oauth to access her Google Talk account. gtalkOauthUrl string The url to open to request Oauth access to the user's Google Talk account. pacUrl1 url The url of Lantern's pac file. nproxies1 int The number of proxies the user can currently connect to. connectingStatus string Message the frontend should display to give feedback to the user about Lantern's progress during the connection process. Some html is allowed; unsafe html will be sanitized. Should be translated into the user's chosen language. peerid string The peerid of this user. type "pc" | "cloud" | "laeproxy" The peer type of this user. lastConnected date The datetime the user was last connected to a peer (i.e. the most recent disconnect from the last remaining peer the user was connected to). Blank if currently connected to some peer. invited boolean Whether the user has been invited to Lantern. gtalk "notConnected" | "connecting" | "connected" Google Talk connectivity status.
peers object[]	List of all peers we've ever connected to. peerid string unique identifier for this peer * Needed because multiple peers for the same user are possible, since a user could be running Lantern from several personal computers and/or sponsoring cloud proxies * Should not reveal identity of associated user rosterEntry object roster entry for this peer if in roster type "pc" | "cloud" | "laeproxy" type of Lantern peer * cloud and laeproxy peers will have users associated with them via kaleidoscope connected boolean whether user is currently connected to this peer lastConnected date time the user last connected to this peer version string (last known) version of client software the peer is running mode "give" | "get" | "unknown" (last known) mode this peer is running in ip string (last known) ip address of peer lat float (last known) latitude of peer (as reported by geoip lookup) lon float (last known) longitude of peer (as reported by geoip lookup) country two-letter code (last known) country of peer (as reported by geoip lookup) bpsUp number instantaneous upload rate to this peer bpsDn number instantaneous download rate from this peer bpsUpDn number instantaneous upload+download rate with this peer bytesUp number lifetime bytes uploaded to this peer bytesDn number lifetime bytes downloaded from this peer bytesUpDn number lifetime bytes transferred with this peer
transfers object	bpsUp number total instantaneous upload rate across all current peers bpsDn number total instantaneous download rate across all current peers bpsUpDn number total instantaneous upload+download rate across all current peers bytesUp number total number of bytes uploaded since first signin bytesDn number total number of bytes downloaded since first signin bytesUpDn number total number of bytes uploaded+downloaded since first signin
profile (OAuth2Login) object	email email The user's e-mail address. name string The user's full name, if available. link url A link to the user's Google Plus page, if available. picture url Url of the user's picture, if available. gender string The user's gender. birthday string The user's birthday in the form YYYY-MM-DD, where YYYY may be "0000" if the contact does not display her birth year. locale string The user's locale code, as in "en".
roster object[]	List of contacts on the user's Google Talk roster with known email addresses. Used for auto-completing by name or email when the user is prompted to select friends to invite or request an invite from. email email Contact's email address. status "offline" | "available" | "idle" | "unavailable" Contact's online status. statusMessage string Contact's status message. name string Contact's full name, if available. picture url Url of the contact's profile picture, if available.
friends object[]	List of the user's Lantern Friends. As in roster, except with an additional status field, which can take the value "friend", "pending", or "rejected".
nproxiedSitesMax int	The maximum number of configured proxied sites allowed.
settings object	lang string The user's language setting as a two-letter ISO 639-1 code. runAtSystemStart boolean Whether Lantern should start up automatically when the user logs in to the system. autoReport boolean Whether the user has enabled automatic error and usage reporting. mode "give" | "get" Whether in give mode or get mode. proxyPort1 int The port the Lantern http proxy is running on. systemProxy1 boolean Whether to try to set Lantern as the system proxy. proxyAllSites1 boolean Whether to proxy all sites or only those on proxiedSites. proxiedSites1 string[] List of domains to proxy traffic to.

1 Only used in Get Mode

---

HTTP API

All of the following endpoints should be accessed via POST request only.

/interaction/<interactionid>	Notify the backend of the user interaction specified by interactionid, optionally passing associated data in a JSON-encoded request body, e.g. POST /interaction/set {"path": "/settings/autoReport", "value": true}
/exception	Notify the backend of the exception described by the JSON-encoded request body. If the user has not opted out of auto-reporting, the backend should report the exception to exceptional.io, adding the current state of the model to the report with any sensitive data filtered out.

---

Reference implementations

lantern-ui's development server includes a mock backend to facilitate testing and development (see README.md). The mock backend implementation, found in the /mock directory, can serve as a reference implementation of these specifications.