Skip to content

Latest commit

 

History

History
668 lines (639 loc) · 28.2 KB

SPECS.md

File metadata and controls

668 lines (639 loc) · 28.2 KB

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": "[email protected]",
    "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
remainingFriendingQuota
int ≥ 0
How many more friends the user can add. Adding friends is limited to discourage promiscuous friending.
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.