pravo serve

Quick reference

The command runs until a signal ends it. The viewer is one page that the server sends from the pravo binary, and a JSON interface that the page reads. The viewer explains what it shows.

Flags

The global flags apply. With --json, the address is printed as one line:

{"port":8700,"token":"3f6d...","url":"http://127.0.0.1:8700/?token=3f6d..."}

With --plan and no -t or -T, the specification is read with the tags that the plan was made with.

There is no flag for the address. The server listens on 127.0.0.1.

Exit codes

What the viewer shows

• The graph. Every resource, data source, ephemeral resource and function call of the specification and of the state, in the module that holds it, with the edges between them. Each node says whether it is declared, recorded or both, whether a read marked it drifted or gone, whether a lock holds it, and how many of its values are withheld.
• The attributes. The record of a node in the order of the provider schema, with the type of each attribute and whether it is required, optional or computed. Sensitive values are withheld.
• The source. The lines of the specification that write the node: the definition of the resource and each instance that fills it in. Only files that the evaluation loaded are shown.
• The schema. The attributes of the resource type with their types and the provider's descriptions.
• The history. The transactions that wrote the node: the kind, the time, the user and actor, and the command. The values of -t tags, and of flags and key=value words that are named like a secret, are withheld from the command.
• The plan. With --plan, the action of the plan for each node and the attributes that it changes, the numbers of its summary and its hints. A plan that cannot be applied is shown with its reasons.
• The project. The directory, the package, the state location, lineage and record count, the providers and the outputs. A sensitive output has no value.

The viewer follows the project. It watches the state, the files that the evaluation loaded and the plan file, and when any of them changes the page fetches the graph again. A specification that does not load is shown as the state alone, with the error as a warning.

The page

The viewer is one page with a bar, a sidebar, a graph with its toolbar, an inspector and a status bar. It follows the system theme until you choose one.

Filters

The chips set filter. The box sets q, which matches an address or a type.

The inspector

The strip above the tabs has the cells Action, Record, Lock, Revision and Refreshed. Action is the action of the plan, no change, not read or no plan. Record is in sync, drifted, gone, declared only or orphan. Lock shows when a lock or a reservation holds the resource.

What it never does

• It writes no state, takes no lock, makes no plan, runs no apply, writes no lock file and generates no package. The project directory and the state hold the same bytes after a session as before it.
• It listens on no interface but loopback.
• It sends no value that the provider schema marks sensitive or write-only, no value of an attribute that the schema does not know, no value of an attribute that is named like a secret, no value that contains a string that the state keeps in a sensitive attribute, and no value of a sensitive output.
• It serves no file by path. A request names an address, and the server looks the address up in the specification that it loaded.

Security model

The viewer reads a state that holds secrets and sends it to a browser. These rules are what stands between the two.

Loopback only. The listener binds 127.0.0.1. A request from another machine does not reach it. Over SSH or in a container, see Explore an estate in a browser.

A token for each run. Each run makes a 128-bit random token and prints it in the address. A request for /?token=TOKEN sets a cookie named pravo_serve_PORT that is HttpOnly and SameSite=Strict, and redirects to / without the token. Every request to /api/ needs that cookie, or the header Authorization: Bearer TOKEN. The server compares tokens in constant time. A request without either gets 401 and a body that names nothing.

A check of the host. A request whose Host is not 127.0.0.1:PORT, localhost:PORT or [::1]:PORT gets 421. A request that another site makes through the browser gets 403, and so does a request to /api/ from another port of the same host or with an Origin header other than the viewer's. Every response carries Cross-Origin-Resource-Policy and Cross-Origin-Opener-Policy set to same-origin. At most 32 event streams are open at once. The server sends no CORS header, so no other page can read its answers. It answers GET and HEAD and refuses every other method with 405.

Redaction on the server. A value is sent only when the provider schema says that it is not sensitive and not write-only. Nested attributes and blocks follow the schema down. These withhold a value too:

The private blob, the configuration hash and the provider configuration of a record are never sent. A response cuts a long list, the text of an attribute at 4 KiB and a block of source at 200 lines.

Source from loaded files only. The server reads the lines of files that the evaluation lists, and of no other path. A request names a resource and never a path. A string literal that is assigned to a sensitive attribute, or to one whose name matches the rule above, is masked in the lines and the line is marked. A line that holds a sensitive string of the state is masked wherever it is. A file is read only if it still resolves to the path that it had when the specification was loaded.

Read-only. Every endpoint is a GET. There is no request that changes the project, the state or a plan.

The state that the specification names. The viewer opens the state backend that the specification configures, as every other command does. For a remote state it prints reading state from s3://BUCKET/PREFIX at the start, with the endpoint when the specification sets one. A specification from a source that you do not trust can name any endpoint: read it before you serve it.

The address of a view

The viewer keeps its view in the fragment of the address, so that a link reproduces a view. A fragment looks like #/?sel=api.services.billing.config&tab=source&collapse=network,edge&theme=dark. Values are URL-encoded, and a list is comma separated. The page rewrites the fragment as you use it, so the address in the bar is always a link to what you see.

Keyboard

The sheet of shortcuts in the viewer opens with ?. Keys other than Ctrl-K and Esc do nothing while a text field has the focus.

In the graph:

In the tree of modules in the sidebar:

In the table, the up and down arrows, Page Up, Page Down, Home and End move the selection. In the palette, the arrows and Page Up and Page Down move, Enter goes to the result and Esc closes it.

Endpoints

The interface of the page is a set of read-only endpoints. They are for the page, and for a script that reads them. They follow the version of pravo: a response carries version, and a layout change raises it. Every response has Cache-Control: no-store, and every /api/ request needs the token.

ADDR is URL-encoded. An address that is not known gets 404 and {"error":"..."}.

Examples

Work in an empty directory named demo.

package demo

import (
	rnd "pravo.dev/providers/hashicorp/random"
	loc "pravo.dev/providers/hashicorp/local"
)

$random: rnd.#Provider
$local:  loc.#Provider

pet: $random.#Resource.random_pet & {length: 2}

config: $local.#Resource.local_file & {
	filename: "server.env"
	content:  "NAME=\(pet.id)\n"
}

Apply complete! Resources: 2 added, 0 changed, 0 destroyed. [txn <id>]

Start the viewer

A script starts the viewer with --json, reads the address from the first line and stops the viewer with a signal. A person runs pravo serve and leaves it running.

{"port":<port>,"token":"<token>","url":"http://127.0.0.1:<port>/?token=<token>"}

Read the interface from a script

Every request to /api/ needs the token. The first request here has none, the second has the token as a bearer token, and the third names a host that the server does not own.

no token: 401
{"ok":true,"version":1}
other host: 421

The flags

Serve a read-only viewer on the loopback interface and open it in the default browser.

The viewer shows the specification and the state as a graph of modules and resources, with the attributes of each (sensitive ones withheld), the CUE that writes it, its provider schema and its history. With --plan it shows a saved plan on top. It updates when the state, the specification or the plan file changes.

The server writes nothing: no state, no lock, no lock file, no generated package. It starts no provider and downloads nothing: it reads the provider schemas that are cached already. It listens on 127.0.0.1 only, and every request needs the token in the address that is printed.

Usage:
  pravo serve [flags]

Flags:
  -h, --help              help for serve
  -T, --inject-vars       inject system tag variables (os, arch, cwd, ...)
      --no-open           do not open a browser
      --plan string       a saved plan to show on top of the graph
      --port int          the port to listen on (0 picks a free one)
  -t, --tag stringArray   inject a value for an @tag() field: -t key=value

Global Flags:
      --actor string    a label for who is acting, recorded on transactions, locks and plans; not verified ($PRAVO_ACTOR)
  -C, --chdir string    run as if started in this directory
      --json            machine-readable output on stdout (progress goes to stderr)
      --no-color        disable coloured output
      --reason string   why; recorded on transactions and plans ($PRAVO_REASON)
  -v, --verbose count   log what pravo decides and does to stderr; -vv adds finer detail and the providers' own log ($PRAVO_LOG=debug|trace)