I volunteer at Code for Boston. I help out with web app development, contributing code and reviewing contributions. All of our projects are open source, run on Github, and follow the fork-and-pull development model.
We built my last two projects using Next.js on Firebase Hosting, and our CI runs on Github Actions. Firebase provides some great tooling: firebase init can set up workflows for CD off of a specific branch and preview deployments for pull requests.
Unfortunately, the preview deployment workflow does not work across forks. Workflows that run on pull requests from forks do not have access to Github secrets. Otherwise, a malicious user could craft a pull request to leak secrets by printing them out. Since we can’t secrets, we can’t provide Firebase credentials to the PR workflow.
Without automated deployments for pull requests, reviewers have to check out the pull request branch and run the site themselves. This can be a significant barrier to participation, especially for non-developers looking at UI.
We automate PR deploys by splitting the workflow into two. We build the application in the PR workflow, store the static files as an artifact, and deploy it using a second workflow triggered using the workflow_run action trigger. This trigger allows running a workflow after the completion of another specified workflow. The triggered workflow always runs at the tip of the default branch. This way, it runs with trusted code, and so has access to secrets.
This workflow runs on each pull request, building the site and uploading to an artifact:
name: Build Pull Request
on: [pull_request]
jobs:
build:
# Don't build forks, even if actions are enabled
if: github.repository_owner == 'codeforboston'
name: Build
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
# Set up the build environment using a local composite action
- name: Setup Build Environment
uses: ./.github/actions/setup-repo
# Build the app, putting the static files in ./out/
- name: Build App
run: yarn export:nolint
# Upload the static files to an artifact
- name: Export App
uses: actions/upload-artifact@v2
if: github.event_name == 'pull_request'
with:
name: digital-testimony-app
path: out
retention-days: 1
This workflow deploys the artifact uploaded by the previous workflow to a preview URL and posts it to the PR conversation for review:
name: Deploy Pull Request
on:
workflow_run:
workflows: ["Build Pull Request"]
types:
- completed
jobs:
deploy:
name: Deploy Pull Request
runs-on: ubuntu-latest
# Don't build forks, even if actions are enabled
if: github.event.workflow_run.conclusion == 'success' && github.repository_owner == 'codeforboston'
environment: dev
steps:
- name: Checkout code
uses: actions/checkout@v2
# Download the site's static files and deploy them to Firebase Hosting
- name: Deploy App to Firebase Hosting
uses: alexjball/action-hosting-deploy@v1
with:
repoToken: "$"
firebaseServiceAccount: "$"
projectId: digital-testimony-dev
artifactName: digital-testimony-app
Note that this workflow runs on the default branch, and so uses the Firebase configuration from that branch. Only the content of the site is affected by the PR.
We reused the Firebase deployment action, patching it to accept the artifactName of the site artifact uploaded in the triggering workflow. The action can resolve the artifact using the Github API.
You can generate a service account for firebaseServiceAccount using firebase init. Just ignore the workflow files it generates.
This process deploys external contributor code. Can this be abused? Not really, at least not any more than one could with a local development frontend, which is publicly accessible. Both use development client keys, and both are allowed domains on our Firebase projects. And the development environment contains no private data, so phishing-styles attacks are not an issue.
Splitting the build and deploy steps between workflows using the workflow_run trigger allowed us to easily deploy pull requests to preview URL’s. This enables more people to participate in reviews and makes it easy to review frontend changes without checking out the PR branch.
The computer in my college dorm’s common space was a thing of beauty. It was connected to a big TV, always on, and had a wireless keyboard-trackpad. Students used it to watch lectures, work on assignments, and most importantly relax together. Its convenience promoted its use, and its flexibility made it an indispensible collaboration tool.
But college is uniquely local. In reality, our connections in work and life are distributed. Conference calls and screen-sharing close some of that distance, but screen-sharing video quality is often low and without audio; and remote collaborators are unable to control the desktop being shared. Remote desktop applications like Chrome Remote Desktop and VNC solve remote control, but only for one user and with low video quality.
I built Share Space to address these problems and to support the vision of a remote shared computer. Users join Share Space rooms using the Share Space web client and the room’s address and passcode. Each room hosts a virtual desktop, streams high-quality video and audio to all members, and allows members to take over remote control of the desktop. Share Space Host makes it easy to self-host room instances.
The most interesting part of this project has been achieving a low-latency (1-3 second) video stream of the desktop. Much of that work was panning for gold among the many specs and RFC’s that make up web video. So I’ll go over the implementation options for modern web video and then explain the design for Share Space’s video streaming.
There are roughly two categories of video solutions.
The Media Source Extensions define the MediaSource class, which can be used to pass video stream buffers from Javascript to the video playback element. This allows implementing streaming players in Javascript and is how modern players support HLS/DASH/etc.
WebRTC defines the WebRTCPeerConnection class, which can be used to set up RTP connections for media and data. RTP (Real-time Transport Protocol) supports lower latency and higher bandwidth than HTTP or WebSockets, and is how web-based video chat is implemented.
WebRTC initially seemed like the best option because of its latency claims. To serve the desktop stream, I would need a server that speaks WebRTC and that could share the encoded stream between all clients. The node-webrtc project provides a Node wrapper around Chromium’s WebRTC implementation. Since browser WebRTC encodes video for each connection, though, the server would encode once for each of its clients, rather than sharing one encoded stream. Other options include the GStreamer WebRTC plugin, Kurento Media Server, and forking Chromium’s implementation.
In every case, the WebRTC protocol stack introduced significant complexity to the streaming component. So instead, I decided to prototype a solution using MediaSource and WebSockets, which turned out to be simpler and good enough for the MVP.
WebRTC will be worth re-evaluating for video/voice chat features and further improving latency. Two paths forward:
node-webrtc to pass the video stream over a data channel, replacing the WebSocket transport currently used.Traditional on-demand video streaming works by breaking up video files into segments and serving each segment over HTTP(S). Players first download a manifest with media information and a mapping from video timestamp ranges to segment URL’s. Players then download the segments, buffering them as the video element decodes and displays the stream. This approach scales well since the segments can easily be cached by content delivery networks.
With this approach, latency is determined by:
Traditionally, the entire segment is encoded before being published, and browsers maintain a buffer of multiple segments to ensure smooth playback. Segments are 2-6 seconds, so this implies a latency of at least 10 seconds.
Optimizations like low-latency HLS use HTTP chunked transfer encoding to stream segments as they’re encoded, allowing 2-5 second latencies. This reduces the latency of (1) and (2) to the propagation time of the CDN.
Since Share Space scales by room, each stream serves a max of 10-20 users, so stream scalability was not a requirement. In that case it’s much simpler to stream video over a WebSocket. Furthermore, the room server need only serve the latest segment as a live stream, so the encoder can write directly to the room server rather than a CDN.
FFMpeg was used to capture the virtual desktop and encode the video stream. A Node server accepts the video stream from FFMpeg and multiplexes it between clients. It also manages connections to VNC controls and authenticates all connections using the room code.
The client feeds the video stream directly into a MediaSource instance using the video/webm; codecs="vp9,vorbis" mimeType. According to the spec, MediaSource expects an initialization segment followed by media segments. Each Cluster element in the WebM stream is a media segment, and everything before the first cluster is the initialization segment.
So in order to multiplex the FFMpeg stream, the server needed to serve the initialization segment to each client before starting to stream the latest media segment. I customized the webm_chunk muxer to write the video stream to the primary FFMpeg output and segment boundary positions to a secondary output, both of which were accepted by the room server. The room server then used this information to split the stream into segments and multiplex the stream between all clients.
MediaSource and WebSockets provide a simple mechanism to serve low-latency video to web clients.
I’d love to hear your recommendations for WebRTC server components!
]]>