• Stars
    star
    133
  • Rank 272,600 (Top 6 %)
  • Language
    TypeScript
  • License
    Mozilla Public Li...
  • Created over 4 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Oxide Web Console

Oxide Web Console

Web client to the Oxide API.

screenshot of instances list page

At https://console-preview.oxide.computer, the console is deployed as a static site with a mock API running in a Service Worker. You can create mock resources and they will persist across client-side navigations, but they exist only in the browser: nobody else can see them and the mock "DB" is reset on pageload. Request and response bodies in the mock API match the Oxide API's OpenAPI spec, but behavior is only mocked in as much detail as is required for development and testing of the console and is not fully representative of the real API.

Goals and principles

  • The console is not an application, it is a client to the application (the Oxide API) — minimize client-side state
  • Be a transparent view onto the API — teach API concepts and avoid making the user learn anything console-specific
  • Simple, predictable, and broadly functional everywhere is better than deeply polished in a few places
  • When we don't have product clarity, build the simplest thing and move on
  • There is enough technical risk elsewhere down the stack, so be conservative:
    • Focus on building things we can be sure we'll need
    • Rely on good libraries that we can use the way they want to be used
    • Building on bad abstractions is costly — duplication is fine while you figure out the right abstraction
  • Linkability — use routes to capture app state
  • Rely on code generated from API spec for correctness

Architecture

console client-server architecture diagram

In order to avoid the complexity of server-side rendering (and running JS on the rack), the web console is a fully client-side React app. We use Vite (which uses Rollup internally for production builds) to build a set of assets (index.html, JS bundles, CSS, fonts, images) and we serve those assets as static files from a special set of console endpoints in Nexus. From the control plane API server's point of view, the web console simply is:

  • a directory of static assets and some endpoints that serve them
  • a few other endpoints to handle auth actions like login/logout
  • a table of sessions (console-specific in practice, but not intrinsically so)

The web console has no special privileges as an API consumer. Logging in sets a cookie, and we make cookie-authed API requests after that. See RFD 223 Web Console Architecture (internal document for now) for a more detailed discussion. The endpoints live in nexus/src/external_api/console_api.rs in Omicron.

Tech

Directory structure

The app is in app. You can see the route structure in app/routes.tsx. Also in app we have a ui dir where the low-level components live and an api dir where we keep the generated API client and a React Query wrapper for it. The latter is aliased in tsconfig.json for easy import from the main app as @oxide/api.

Development

Node.js version

Use Node.js v18+.

Install dependencies

npm install
npx playwright install # only needed to run e2e tests

Run Vite dev server + MSW mock API

This is the way we do most console development. Just run:

npm run dev

and navigate to http://localhost:4000 in the browser. The running app will automatically update when you write a source file. This mode uses Mock Service Worker to run a mock API right the browser. This mock API is also used in tests.

Specifying non-default user

Pick a user from the list of users in mock-api/user.ts. The one without fleet viewer permissions is Hans Jonas. Open the browser console and run:

document.cookie = 'msw-user=Hans Jonas;domain=localhost;path=/'

You are now user Hans Jonas. To go back to the default, delete the cookie. (We will get the mock API to clear the cookie for you on logout soon.)

Run Vite dev server against local Nexus API

You can also run the console dev server locally with the mock server off, instead passing requests through to localhost:12220. Run npm run start:nexus and navigate to http://localhost:4000/login/test-suite-silo/local in the browser. It will not work unless Nexus is running at localhost:12220, which is the default for omicron-dev (see Running Omicron (Simulated) for how to set that up).

One way to run everything is to use the tools/start_api.sh script, which uses tmux to run multiple processes in different panes and automatically populates some fake data (see tools/populate_omicron_data.sh to see exactly what). From the omicron directory, run tools/start_api.sh. Since we're assuming console and omicron are next to each other, that looks like this:

../console/tools/start_api.sh

Run local dev server against the dogfood rack

  1. Get on the VPN
  2. Run npm run start:dogfood
  3. Go to https://localhost:4000 (note the https). The page won't work yet, and you'll get redirected to /login, which will look like a 404
  4. Go to https://oxide.sys.rack2.eng.oxide.computer in another tab and log in
  5. Open the dev tools Storage tab and copy the session cookie value, which should look like d9b1a96e151092eb0ea08b1a0d8c4788441f1894
  6. Go back to your localhost tab, open the developer console, and run
document.cookie = 'session=d9b1a96e151092eb0ea08b1a0d8c4788441f1894;domain=localhost;path=/'

Go to https://localhost:4000 again and you should be logged in.

Run Ladle

npm run ladle

This will start a preview environment for UI components at http://localhost:61000.

E2E tests with Playwright

Playwright tests live in test/e2e. npm run e2e runs the tests in Chrome, Firefox, and Safari, but this is rarely necessary in local dev. npm run e2ec is a shortcut for playwright test --project=chrome, which runs the tests in Chrome only (the fastest one, useful for local dev). Playwright has an excellent UI mode for running and debugging tests that you can get to by running npm run e2e -- --ui.

To debug end-to-end failures on CI, check out the branch with the failure and run ./tools/debug-ci-e2e-fail.sh. It'll download the latest failures from CI and allow you to open a playwright trace of the failure.

Summary of useful commands

Command Description
npm run dev Run Vite dev server with mock API
npm test Vitest unit tests
npm run e2ec Run Playwright E2E tests in Chrome only
npm run lint ESLint
npx tsc Check types
npm run ci Lint, tests (unit and e2e), and types
npm run ladle Run Ladle (Storybook)
npm run fmt Format everything. Rarely necessary thanks to editor integration
npm run gen-api Generate API client (see docs/update-pinned-api.md)
npm run start:mock-api Serve mock API on port 12220

Relevant RFDs

More Repositories

1

hubris

A lightweight, memory-protected, message-passing kernel for deeply embedded systems.
Rust
2,912
star
2

dropshot

expose REST APIs from a Rust program
Rust
855
star
3

progenitor

An OpenAPI client generator
Rust
522
star
4

humility

Debugger for Hubris
Rust
452
star
5

typify

compiler from JSON Schema into idiomatic Rust types
Rust
425
star
6

helios

Helios: Or, a Vision in a Dream. A Fragment.
Rust
367
star
7

oxide-and-friends

Show notes from Oxide and Friends recordings
Rust
308
star
8

omicron

Omicron: Oxide control plane
Rust
251
star
9

cio

Rust libraries for APIs needed by our automated CIO.
Rust
247
star
10

propolis

VMM userspace for illumos bhyve
Rust
175
star
11

crucible

A storage service.
Rust
170
star
12

p4

A P4 compiler
Rust
105
star
13

design-site

We are looking for designers who code to help build a new user experience for computing!
CSS
99
star
14

cobalt

A collection of common Bluespec interfaces/modules.
Bluespec
96
star
15

third-party-api-clients

A place for keeping all our generated third party API clients.
Rust
89
star
16

usdt

Dust your Rust with USDT probes
Rust
84
star
17

steno

distributed sagas
Rust
75
star
18

phbl

Pico Host Boot Loader
Rust
69
star
19

tockilator

Deducing Tock execution flows from Ibex Verilator traces
Rust
68
star
20

serde_tokenstream

serde::Deserializer for proc_macro/proc_macro2::TokenStream
Rust
63
star
21

buildomat

a software build labour-saving device
Rust
55
star
22

oxide.rs

The Oxide Rust SDK and CLI
Rust
38
star
23

opte

packets go in, packets go out, you can't explain that
Rust
36
star
24

fable

TOML deck generator with custom templates and schema validation
CSS
34
star
25

cancel-safe-futures

Alternative future adapters that provide cancel safety.
Rust
33
star
26

helios-engvm

Tools for creating and using Helios images on i86pc (classic PC) physical and virtual machines
Rust
30
star
27

pki-playground

Tool for generating non-trivial X.509 certificate chains
Rust
28
star
28

expectorate

I'm especially good at expectorating
Rust
27
star
29

maghemite

A routing stack written in Rust.
Rust
26
star
30

oxide.ts

TypeScript client for the Oxide API
TypeScript
24
star
31

aws-wire-lengths

simple command line for various AWS management tasks
Rust
23
star
32

fs3-rs

Extended utilities for working with files and filesystems in Rust.
Rust
22
star
33

lpc-link2-re

Reverse engineering the LPC-Link2 USB interface
Rust
22
star
34

lethe

A basic log-structured flash datastore
Rust
20
star
35

terraform-provider-oxide

Oxide Terraform provider
Go
18
star
36

poptrie

A poptrie implementation
Rust
17
star
37

oxide.go

The Go SDK for Oxide.
Go
17
star
38

cli-old

The command line tool for Oxide.
Rust
16
star
39

design-system

Home of reusable design assets and tokens for oxide internal sites
TypeScript
15
star
40

rfsx

A XMODEM sender using libftdi
Rust
15
star
41

amd-apcb

AMD Generic Encapsulated Software Architecture Platform Security Processor Configuration Block manipulation library
Rust
14
star
42

rustfmt-wrapper

A simple wrapper around rustfmt to use it as a library for use when generating code
Rust
14
star
43

rfb

Rust
13
star
44

async-bb8-diesel

Safe asynchronous access to Diesel and the bb8 connection manager
Rust
12
star
45

xfr

An atomic ring for processing memory-mapped frames.
Rust
11
star
46

idolatry

An experimental IPC interface definition language for Hubris.
Rust
11
star
47

bootleby

Rust
11
star
48

openapi-lint

Validate an OpenAPI schema against some rules
Rust
11
star
49

dropkick

punt your dropshot service into the cloud
Rust
10
star
50

zone

Rust
10
star
51

hif

HIF: The Hubris/Humility Interchange Format
Rust
10
star
52

bhyve-api

Rust library interface to Bhyve ioctl API
Rust
9
star
53

overwatch

A P4-powered packet tracer.
Rust
9
star
54

offline-keystore

yubihsm-setup replacing the yubico cruft with our own cruft!
Rust
9
star
55

react-asciidoc

A React renderer for AsciiDoc. Built on top of Asciidoctor.js.
JavaScript
9
star
56

eos

A build tool for illumos.
Rust
8
star
57

ch-oxidase

A port of Cloud Hypervisor to run on Illumos and the Bhyve kernel space
Rust
8
star
58

softnpu

Software Network Processing Unit
Rust
8
star
59

sprockets

Now's the time on sprockets when we dance
Rust
7
star
60

wfm-to-pcap

.wfm to .pcap decoder
Rust
7
star
61

transceiver-control

Crate for controlling optical transceivers over the network
Rust
7
star
62

lpc55_support

Support tooling for flashing the LPC55
Rust
7
star
63

reqwest-conditional-middleware

A middleware wrapper that enables (or disables) a wrapped Reqwest middleware on a per-request basis
Rust
7
star
64

lpc55s69_rompatch_sample

A sample showing issues with the LPC55 mystery rom patch
C
6
star
65

diesel-dtrace

A diesel connection with DTrace probes for connections and queries
Rust
6
star
66

miniz

toy in-memory implementation of Zanzibar data model
Rust
6
star
67

dice-util

utilities for cert template generation and manufacturing / certifying DeviceIds
Rust
6
star
68

sshauth

A library for SSH key based (agents or static files) authentication tokens
Rust
6
star
69

garbage-compactor

terrible build scripts
Shell
6
star
70

slog-dtrace

A slog drain for emitting logging messages to DTrace
Rust
5
star
71

falcon

Fast Assessment Laboratory for Computers On Networks
Rust
5
star
72

smf

Rust
5
star
73

p9fs

A Plan 9 file system crate
Rust
5
star
74

ispf

An Internet packet format Serde implementation
Rust
5
star
75

nixie-tubes

Oxide's collection of assorted NixOS thingamajigs
Nix
5
star
76

tlvc

TLV-C encoding support.
Rust
5
star
77

thouart

Some helpful code for implementing CLI tools for connecting to simulated remote terminals
Rust
5
star
78

clock

wall clock software for the Oxide office
Rust
5
star
79

qemu-systick-bug

Program demonstrating bug in QEMU's SysTick emulation
Rust
4
star
80

tsc-simulator

Rust tool to calculate and simulate the TSC and other time-related values for live migration
Rust
4
star
81

pmbus

A no_std crate for PMBus manipulation
Rust
4
star
82

qorb

Rust
4
star
83

identicon

TypeScript
4
star
84

helios-omicron-brand

A zone brand for Omicron components running under Helios
Rust
4
star
85

cockroach

CockroachDB 22.1.x long-term maintenance branch
Go
3
star
86

serde_human_bytes

Serialize [u8; N] as bytes or as human-readable strings, depending on the format.
Rust
3
star
87

oxide.rs-old

The Rust API client for Oxide.
Rust
3
star
88

sb2_poc

Proof of concept for SB2 exploits
C
3
star
89

dhcpv6

dhpcv6 encoding/decoding
Rust
3
star
90

netadm-sys

A network administration library and CLI for illumos
Rust
3
star
91

tofino

tofino support stuff
Rust
3
star
92

omicron-package

Tools to create Omicron-branded Zones
Rust
3
star
93

partial-struct

Rust
3
star
94

slog-error-chain

Logging Rust errors with context
Rust
3
star
95

renovate-config

Oxide's shared renovate configuration
3
star
96

ordered-toml

toml-rs except preserves table ordering
Rust
3
star
97

management-gateway-service

Crates shared between MGS in omicron and its agent task in hubris
Rust
3
star
98

kstat-rs

Rust interface to illumos libkstat
Rust
3
star
99

tree-sitter-p4

P4 grammar for tree-sitter
JavaScript
3
star
100

helios-omnios-build

Shell
3
star