@supabase/phoenix 0.1.0

package/assets/js/phoenix/index.js

@@ -0,0 +1,212 @@
+/**
+ * Phoenix Channels JavaScript client
+ *
+ * ## Socket Connection
+ *
+ * A single connection is established to the server and
+ * channels are multiplexed over the connection.
+ * Connect to the server using the `Socket` class:
+ *
+ * ```javascript
+ * let socket = new Socket("/socket", {params: {userToken: "123"}})
+ * socket.connect()
+ * ```
+ *
+ * The `Socket` constructor takes the mount point of the socket,
+ * the authentication params, as well as options that can be found in
+ * the Socket docs, such as configuring the `LongPoll` transport, and
+ * heartbeat.
+ *
+ * ## Channels
+ *
+ * Channels are isolated, concurrent processes on the server that
+ * subscribe to topics and broker events between the client and server.
+ * To join a channel, you must provide the topic, and channel params for
+ * authorization. Here's an example chat room example where `"new_msg"`
+ * events are listened for, messages are pushed to the server, and
+ * the channel is joined with ok/error/timeout matches:
+ *
+ * ```
+ * let channel = socket.channel("room:123", {token: roomToken})
+ * channel.on("new_msg", msg => console.log("Got message", msg) )
+ * $input.onEnter( e => {
+ *   channel.push("new_msg", {body: e.target.val}, 10000)
+ *     .receive("ok", (msg) => console.log("created message", msg) )
+ *     .receive("error", (reasons) => console.log("create failed", reasons) )
+ *     .receive("timeout", () => console.log("Networking issue...") )
+ * })
+ *
+ * channel.join()
+ *   .receive("ok", ({messages}) => console.log("catching up", messages) )
+ *   .receive("error", ({reason}) => console.log("failed join", reason) )
+ *   .receive("timeout", () => console.log("Networking issue. Still waiting..."))
+ *```
+ *
+ * ## Joining
+ *
+ * Creating a channel with `socket.channel(topic, params)`, binds the params to
+ * `channel.params`, which are sent up on `channel.join()`.
+ * Subsequent rejoins will send up the modified params for
+ * updating authorization params, or passing up last_message_id information.
+ * Successful joins receive an "ok" status, while unsuccessful joins
+ * receive "error".
+ *
+ * With the default serializers and WebSocket transport, JSON text frames are
+ * used for pushing a JSON object literal. If an `ArrayBuffer` instance is provided,
+ * binary encoding will be used and the message will be sent with the binary
+ * opcode.
+ *
+ * *Note*: binary messages are only supported on the WebSocket transport.
+ *
+ * ## Duplicate Join Subscriptions
+ *
+ * While the client may join any number of topics on any number of channels,
+ * the client may only hold a single subscription for each unique topic at any
+ * given time. When attempting to create a duplicate subscription,
+ * the server will close the existing channel, log a warning, and
+ * spawn a new channel for the topic. The client will have their
+ * `channel.onClose` callbacks fired for the existing channel, and the new
+ * channel join will have its receive hooks processed as normal.
+ *
+ * ## Pushing Messages
+ *
+ * From the previous example, we can see that pushing messages to the server
+ * can be done with `channel.push(eventName, payload)` and we can optionally
+ * receive responses from the push. Additionally, we can use
+ * `receive("timeout", callback)` to abort waiting for our other `receive` hooks
+ *  and take action after some period of waiting. The default timeout is 10000ms.
+ *
+ *
+ * ## Socket Hooks
+ *
+ * Lifecycle events of the multiplexed connection can be hooked into via
+ * `socket.onError()` and `socket.onClose()` events, ie:
+ *
+ * ```
+ * socket.onError( () => console.log("there was an error with the connection!") )
+ * socket.onClose( () => console.log("the connection dropped") )
+ * ```
+ *
+ *
+ * ## Channel Hooks
+ *
+ * For each joined channel, you can bind to `onError` and `onClose` events
+ * to monitor the channel lifecycle, ie:
+ *
+ * ```
+ * channel.onError( () => console.log("there was an error!") )
+ * channel.onClose( () => console.log("the channel has gone away gracefully") )
+ * ```
+ *
+ * ### onError hooks
+ *
+ * `onError` hooks are invoked if the socket connection drops, or the channel
+ * crashes on the server. In either case, a channel rejoin is attempted
+ * automatically in an exponential backoff manner.
+ *
+ * ### onClose hooks
+ *
+ * `onClose` hooks are invoked only in two cases. 1) the channel explicitly
+ * closed on the server, or 2). The client explicitly closed, by calling
+ * `channel.leave()`
+ *
+ *
+ * ## Presence
+ *
+ * The `Presence` object provides features for syncing presence information
+ * from the server with the client and handling presences joining and leaving.
+ *
+ * ### Syncing state from the server
+ *
+ * To sync presence state from the server, first instantiate an object and
+ * pass your channel in to track lifecycle events:
+ *
+ * ```
+ * let channel = socket.channel("some:topic")
+ * let presence = new Presence(channel)
+ * ```
+ *
+ * Next, use the `presence.onSync` callback to react to state changes
+ * from the server. For example, to render the list of users every time
+ * the list changes, you could write:
+ *
+ * ```
+ * presence.onSync(() => {
+ *   myRenderUsersFunction(presence.list())
+ * })
+ * ```
+ *
+ * ### Listing Presences
+ *
+ * `presence.list` is used to return a list of presence information
+ * based on the local state of metadata. By default, all presence
+ * metadata is returned, but a `listBy` function can be supplied to
+ * allow the client to select which metadata to use for a given presence.
+ * For example, you may have a user online from different devices with
+ * a metadata status of "online", but they have set themselves to "away"
+ * on another device. In this case, the app may choose to use the "away"
+ * status for what appears on the UI. The example below defines a `listBy`
+ * function which prioritizes the first metadata which was registered for
+ * each user. This could be the first tab they opened, or the first device
+ * they came online from:
+ *
+ * ```
+ * let listBy = (id, {metas: [first, ...rest]}) => {
+ *   first.count = rest.length + 1 // count of this user's presences
+ *   first.id = id
+ *   return first
+ * }
+ * let onlineUsers = presence.list(listBy)
+ * ```
+ *
+ * ### Handling individual presence join and leave events
+ *
+ * The `presence.onJoin` and `presence.onLeave` callbacks can be used to
+ * react to individual presences joining and leaving the app. For example:
+ *
+ * ```
+ * let presence = new Presence(channel)
+ *
+ * // detect if user has joined for the 1st time or from another tab/device
+ * presence.onJoin((id, current, newPres) => {
+ *   if(!current){
+ *     console.log("user has entered for the first time", newPres)
+ *   } else {
+ *     console.log("user additional presence", newPres)
+ *   }
+ * })
+ *
+ * // detect if user has left from all tabs/devices, or is still present
+ * presence.onLeave((id, current, leftPres) => {
+ *   if(current.metas.length === 0){
+ *     console.log("user has left from all devices", leftPres)
+ *   } else {
+ *     console.log("user left from a device", leftPres)
+ *   }
+ * })
+ * // receive presence data from server
+ * presence.onSync(() => {
+ *   displayUsers(presence.list())
+ * })
+ * ```
+ * @module phoenix
+ */
+
+import Channel from "./channel"
+import LongPoll from "./longpoll"
+import Presence from "./presence"
+import Serializer from "./serializer"
+import Socket from "./socket"
+import Timer from "./timer"
+import Push from "./push"
+export * from "./types"
+
+export {
+  Channel,
+  LongPoll,
+  Presence,
+  Push,
+  Serializer,
+  Socket,
+  Timer
+}

package/assets/js/phoenix/longpoll.js

@@ -0,0 +1,192 @@
+import {
+  SOCKET_STATES,
+  TRANSPORTS,
+  AUTH_TOKEN_PREFIX
+} from "./constants"
+
+import Ajax from "./ajax"
+
+let arrayBufferToBase64 = (buffer) => {
+  let binary = ""
+  let bytes = new Uint8Array(buffer)
+  let len = bytes.byteLength
+  for(let i = 0; i < len; i++){ binary += String.fromCharCode(bytes[i]) }
+  return btoa(binary)
+}
+
+export default class LongPoll {
+
+  constructor(endPoint, protocols){
+    // we only support subprotocols for authToken
+    // ["phoenix", "base64url.bearer.phx.BASE64_ENCODED_TOKEN"]
+    if(protocols && protocols.length === 2 && protocols[1].startsWith(AUTH_TOKEN_PREFIX)){
+      this.authToken = atob(protocols[1].slice(AUTH_TOKEN_PREFIX.length))
+    }
+    this.endPoint = null
+    this.token = null
+    this.skipHeartbeat = true
+    this.reqs = new Set()
+    this.awaitingBatchAck = false
+    this.currentBatch = null
+    this.currentBatchTimer = null
+    this.batchBuffer = []
+    this.onopen = function (){ } // noop
+    this.onerror = function (){ } // noop
+    this.onmessage = function (){ } // noop
+    this.onclose = function (){ } // noop
+    this.pollEndpoint = this.normalizeEndpoint(endPoint)
+    this.readyState = SOCKET_STATES.connecting
+    // we must wait for the caller to finish setting up our callbacks and timeout properties
+    setTimeout(() => this.poll(), 0)
+  }
+
+  normalizeEndpoint(endPoint){
+    return (endPoint
+      .replace("ws://", "http://")
+      .replace("wss://", "https://")
+      .replace(new RegExp("(.*)\/" + TRANSPORTS.websocket), "$1/" + TRANSPORTS.longpoll))
+  }
+
+  endpointURL(){
+    return Ajax.appendParams(this.pollEndpoint, {token: this.token})
+  }
+
+  closeAndRetry(code, reason, wasClean){
+    this.close(code, reason, wasClean)
+    this.readyState = SOCKET_STATES.connecting
+  }
+
+  ontimeout(){
+    this.onerror("timeout")
+    this.closeAndRetry(1005, "timeout", false)
+  }
+
+  isActive(){ return this.readyState === SOCKET_STATES.open || this.readyState === SOCKET_STATES.connecting }
+
+  poll(){
+    const headers = {"Accept": "application/json"}
+    if(this.authToken){
+      headers["X-Phoenix-AuthToken"] = this.authToken
+    }
+    this.ajax("GET", headers, null, () => this.ontimeout(), resp => {
+      if(resp){
+        var {status, token, messages} = resp
+        if(status === 410 && this.token !== null){
+          // In case we already have a token, this means that our existing session
+          // is gone. We fail so that the client rejoins its channels.
+          this.onerror(410)
+          this.closeAndRetry(3410, "session_gone", false)
+          return
+        }
+        this.token = token
+      } else {
+        status = 0
+      }
+
+      switch(status){
+        case 200:
+          messages.forEach(msg => {
+            // Tasks are what things like event handlers, setTimeout callbacks,
+            // promise resolves and more are run within.
+            // In modern browsers, there are two different kinds of tasks,
+            // microtasks and macrotasks.
+            // Microtasks are mainly used for Promises, while macrotasks are
+            // used for everything else.
+            // Microtasks always have priority over macrotasks. If the JS engine
+            // is looking for a task to run, it will always try to empty the
+            // microtask queue before attempting to run anything from the
+            // macrotask queue.
+            //
+            // For the WebSocket transport, messages always arrive in their own
+            // event. This means that if any promises are resolved from within,
+            // their callbacks will always finish execution by the time the
+            // next message event handler is run.
+            //
+            // In order to emulate this behaviour, we need to make sure each
+            // onmessage handler is run within its own macrotask.
+            setTimeout(() => this.onmessage({data: msg}), 0)
+          })
+          this.poll()
+          break
+        case 204:
+          this.poll()
+          break
+        case 410:
+          this.readyState = SOCKET_STATES.open
+          this.onopen({})
+          this.poll()
+          break
+        case 403:
+          this.onerror(403)
+          this.close(1008, "forbidden", false)
+          break
+        case 0:
+        case 500:
+          this.onerror(500)
+          this.closeAndRetry(1011, "internal server error", 500)
+          break
+        default: throw new Error(`unhandled poll status ${status}`)
+      }
+    })
+  }
+
+  // we collect all pushes within the current event loop by
+  // setTimeout 0, which optimizes back-to-back procedural
+  // pushes against an empty buffer
+
+  send(body){
+    if(typeof(body) !== "string"){ body = arrayBufferToBase64(body) }
+    if(this.currentBatch){
+      this.currentBatch.push(body)
+    } else if(this.awaitingBatchAck){
+      this.batchBuffer.push(body)
+    } else {
+      this.currentBatch = [body]
+      this.currentBatchTimer = setTimeout(() => {
+        this.batchSend(this.currentBatch)
+        this.currentBatch = null
+      }, 0)
+    }
+  }
+
+  batchSend(messages){
+    this.awaitingBatchAck = true
+    this.ajax("POST", {"Content-Type": "application/x-ndjson"}, messages.join("\n"), () => this.onerror("timeout"), resp => {
+      this.awaitingBatchAck = false
+      if(!resp || resp.status !== 200){
+        this.onerror(resp && resp.status)
+        this.closeAndRetry(1011, "internal server error", false)
+      } else if(this.batchBuffer.length > 0){
+        this.batchSend(this.batchBuffer)
+        this.batchBuffer = []
+      }
+    })
+  }
+
+  close(code, reason, wasClean){
+    for(let req of this.reqs){ req.abort() }
+    this.readyState = SOCKET_STATES.closed
+    let opts = Object.assign({code: 1000, reason: undefined, wasClean: true}, {code, reason, wasClean})
+    this.batchBuffer = []
+    clearTimeout(this.currentBatchTimer)
+    this.currentBatchTimer = null
+    if(typeof(CloseEvent) !== "undefined"){
+      this.onclose(new CloseEvent("close", opts))
+    } else {
+      this.onclose(opts)
+    }
+  }
+
+  ajax(method, headers, body, onCallerTimeout, callback){
+    let req
+    let ontimeout = () => {
+      this.reqs.delete(req)
+      onCallerTimeout()
+    }
+    req = Ajax.request(method, this.endpointURL(), headers, body, this.timeout, ontimeout, resp => {
+      this.reqs.delete(req)
+      if(this.isActive()){ callback(resp) }
+    })
+    this.reqs.add(req)
+  }
+}

package/assets/js/phoenix/presence.js

@@ -0,0 +1,208 @@
+/**
+ * @import Channel from "./channel"
+ * @import { PresenceEvents, PresenceOnJoin, PresenceOnLeave, PresenceOnSync, PresenceState, PresenceDiff, PresenceOptions } from "./types"
+ */
+export default class Presence {
+
+  /**
+   * Initializes the Presence
+   * @param {Channel} channel - The Channel
+   * @param {PresenceOptions} [opts] - The options, for example `{events: {state: "state", diff: "diff"}}`
+   */
+  constructor(channel, opts = {}){
+    let events = opts.events || /** @type {PresenceEvents} */ ({state: "presence_state", diff: "presence_diff"})
+    /** @type{Record<string, PresenceState>} */
+    this.state = {}
+    /** @type{PresenceDiff[]} */
+    this.pendingDiffs = []
+    /** @type{Channel} */
+    this.channel = channel
+    /** @type{?number} */
+    this.joinRef = null
+    /** @type{({ onJoin: PresenceOnJoin; onLeave: PresenceOnLeave; onSync: PresenceOnSync })} */
+    this.caller = {
+      onJoin: function (){ },
+      onLeave: function (){ },
+      onSync: function (){ }
+    }
+
+    this.channel.on(events.state, newState => {
+      let {onJoin, onLeave, onSync} = this.caller
+
+      this.joinRef = this.channel.joinRef()
+      this.state = Presence.syncState(this.state, newState, onJoin, onLeave)
+
+      this.pendingDiffs.forEach(diff => {
+        this.state = Presence.syncDiff(this.state, diff, onJoin, onLeave)
+      })
+      this.pendingDiffs = []
+      onSync()
+    })
+
+    this.channel.on(events.diff, diff => {
+      let {onJoin, onLeave, onSync} = this.caller
+
+      if(this.inPendingSyncState()){
+        this.pendingDiffs.push(diff)
+      } else {
+        this.state = Presence.syncDiff(this.state, diff, onJoin, onLeave)
+        onSync()
+      }
+    })
+  }
+
+  /**
+   * @param {PresenceOnJoin} callback
+   */
+  onJoin(callback){ this.caller.onJoin = callback }
+
+  /**
+   * @param {PresenceOnLeave} callback
+   */
+  onLeave(callback){ this.caller.onLeave = callback }
+
+  /**
+   * @param {PresenceOnSync} callback
+   */
+  onSync(callback){ this.caller.onSync = callback }
+
+  /**
+   * Returns the array of presences, with selected metadata.
+   *
+   * @template [T=PresenceState]
+   * @param {((key: string, obj: PresenceState) => T)} [by]
+   *
+   * @returns {T[]}
+   */
+  list(by){ return Presence.list(this.state, by) }
+
+  inPendingSyncState(){
+    return !this.joinRef || (this.joinRef !== this.channel.joinRef())
+  }
+
+  // lower-level public static API
+
+  /**
+   * Used to sync the list of presences on the server
+   * with the client's state. An optional `onJoin` and `onLeave` callback can
+   * be provided to react to changes in the client's local presences across
+   * disconnects and reconnects with the server.
+   *
+   * @param {Record<string, PresenceState>} currentState
+   * @param {Record<string, PresenceState>} newState
+   * @param {PresenceOnJoin} onJoin
+   * @param {PresenceOnLeave} onLeave
+   *
+   * @returns {Record<string, PresenceState>}
+   */
+  static syncState(currentState, newState, onJoin, onLeave){
+    let state = this.clone(currentState)
+    let joins = {}
+    let leaves = {}
+
+    this.map(state, (key, presence) => {
+      if(!newState[key]){
+        leaves[key] = presence
+      }
+    })
+    this.map(newState, (key, newPresence) => {
+      let currentPresence = state[key]
+      if(currentPresence){
+        let newRefs = newPresence.metas.map(m => m.phx_ref)
+        let curRefs = currentPresence.metas.map(m => m.phx_ref)
+        let joinedMetas = newPresence.metas.filter(m => curRefs.indexOf(m.phx_ref) < 0)
+        let leftMetas = currentPresence.metas.filter(m => newRefs.indexOf(m.phx_ref) < 0)
+        if(joinedMetas.length > 0){
+          joins[key] = newPresence
+          joins[key].metas = joinedMetas
+        }
+        if(leftMetas.length > 0){
+          leaves[key] = this.clone(currentPresence)
+          leaves[key].metas = leftMetas
+        }
+      } else {
+        joins[key] = newPresence
+      }
+    })
+    return this.syncDiff(state, {joins: joins, leaves: leaves}, onJoin, onLeave)
+  }
+
+  /**
+   *
+   * Used to sync a diff of presence join and leave
+   * events from the server, as they happen. Like `syncState`, `syncDiff`
+   * accepts optional `onJoin` and `onLeave` callbacks to react to a user
+   * joining or leaving from a device.
+   *
+   * @param {Record<string, PresenceState>} state
+   * @param {PresenceDiff} diff
+   * @param {PresenceOnJoin} onJoin
+   * @param {PresenceOnLeave} onLeave
+   *
+   * @returns {Record<string, PresenceState>}
+   */
+  static syncDiff(state, diff, onJoin, onLeave){
+    let {joins, leaves} = this.clone(diff)
+    if(!onJoin){ onJoin = function (){ } }
+    if(!onLeave){ onLeave = function (){ } }
+
+    this.map(joins, (key, newPresence) => {
+      let currentPresence = state[key]
+      state[key] = this.clone(newPresence)
+      if(currentPresence){
+        let joinedRefs = state[key].metas.map(m => m.phx_ref)
+        let curMetas = currentPresence.metas.filter(m => joinedRefs.indexOf(m.phx_ref) < 0)
+        state[key].metas.unshift(...curMetas)
+      }
+      onJoin(key, currentPresence, newPresence)
+    })
+    this.map(leaves, (key, leftPresence) => {
+      let currentPresence = state[key]
+      if(!currentPresence){ return }
+      let refsToRemove = leftPresence.metas.map(m => m.phx_ref)
+      currentPresence.metas = currentPresence.metas.filter(p => {
+        return refsToRemove.indexOf(p.phx_ref) < 0
+      })
+      onLeave(key, currentPresence, leftPresence)
+      if(currentPresence.metas.length === 0){
+        delete state[key]
+      }
+    })
+    return state
+  }
+
+  /**
+   * Returns the array of presences, with selected metadata.
+   *
+   * @template [T=PresenceState]
+   * @param {Record<string, PresenceState>} presences
+   * @param {((key: string, obj: PresenceState) => T)} [chooser]
+   *
+   * @returns {T[]}
+   */
+  static list(presences, chooser){
+    if(!chooser){ chooser = function (key, pres){ return pres } }
+
+    return this.map(presences, (key, presence) => {
+      return chooser(key, presence)
+    })
+  }
+
+  // private
+
+  /**
+  * @template T
+  * @param {Record<string, PresenceState>} obj
+  * @param {(key: string, obj: PresenceState) => T} func
+  */
+  static map(obj, func){
+    return Object.getOwnPropertyNames(obj).map(key => func(key, obj[key]))
+  }
+
+  /**
+  * @template T
+  * @param {T} obj
+  * @returns {T}
+  */
+  static clone(obj){ return JSON.parse(JSON.stringify(obj)) }
+}