REST interface

After 0.0.8. The gridnode endpoints, file storage through /storage with its 64 GiB limit, and the storage settings spork are on the master branch and not in release 0.0.8.

A running Hedgehog node can be controlled and queried over HTTPS, on a port separate from the one it uses to talk to other nodes. Operators use it to manage the network settings the board maintains, to inspect and edit the node’s list of peers, to start or stop a gridnode, and to store and retrieve files on the network. The hedgehog cli command is simply a client of this interface, so everything it can do, any other program can do as well.

What it offers

The interface is a set of web resources, grouped by purpose:

  • Grid sporks. Read the network-wide settings described in Grid sporks, see the log of who signed each change, list proposed changes, propose a new value, co-sign a proposal and renew the stored settings. A change takes effect only after two different board keys have signed it.
  • Peers. List the nodes this node knows about, and add or remove one. See Peer-to-peer network protocol for how nodes talk to each other.
  • Gridnode. Start or stop announcing this node as a gridnode, list the known gridnodes and read the collateral required for the current number of active ones.
  • File storage. Store a file and get back a fingerprint, then read or delete it with that fingerprint. The data is spread over gridnodes with erasure coding, as described in Network storage and Erasure coding.
  • Legacy chain data. Look up the balance and transactions of an address in the legacy chain snapshot, including mints still waiting to be paid out. See Legacy chain snapshot.
  • Node control. Report the version, the chain height and the download status of the snapshot, and shut the node down.
  • S3-style buckets. A small subset of the Amazon S3 object-store operations (create, list and delete buckets; put, get, copy, list and delete objects) kept in the node’s own data directory. These files stay on the one node and are not replicated.

How it works

The node runs an HTTPS server next to its peer-to-peer listener. Each request passes a token check first and is then handed to the matching resource, which reads or changes the same state the rest of the daemon uses. For how this listener fits with the other parts of the daemon, see Architecture overview.

flowchart LR
    A[HTTPS request] --> B[Bearer token check]
    B --> C[Resource class]
    C --> D[Daemon state<br/>sporks, peers, storage]
    D --> E[JSON response]

Authentication. Every request must carry the header Authorization: Bearer <token>, including requests for paths that do not exist. The token is taken from --resttoken or the environment variable HEDGEHOG_REST_TOKEN. When neither is set, the node generates a random token at each start and writes it to a file named rest.token in its data directory, readable only by its owner, so a hedgehog cli on the same machine works without configuration. A client on another machine passes the token explicitly.

Encryption. The server uses a self-signed certificate created at each start. The bundled client accepts any certificate, so the connection is encrypted but the server is not authenticated. For this reason the interface listens on localhost by default and should be exposed beyond it only with that in mind.

Changing sporks takes two keys. The endpoints that propose a change (mint storage, mint supply, vesting storage and storage settings) need a privateKey header holding a board member’s private key. The node signs the proposal and answers that it is accepted but pending. A second board member then co-signs it by its digest, and only then is the change stored and published to the network. The same signing rule is described in Grid sporks.

Uploads. File storage through /storage accepts files up to the limit in the table below and streams them, so a large file does not need to fit in memory. The fingerprint returned on upload is the only key to the file and is sent in a header rather than in the URL.

Key facts

Item Value
Protocol HTTPS with a self-signed certificate
Default address localhost, port 52884 (options --resthost, --restport)
Peer-to-peer port, for comparison 52883, listening on all addresses by default
Authentication Bearer token on every request (--resttoken, HEDGEHOG_REST_TOKEN or rest.token)
Largest file through /storage 64 GiB
Largest upload to the S3-style buckets 1 GiB by default (--restmaxupload)
Data format JSON; XML for the S3-style buckets
Protocol versions reported by /version hedgehog/0.0.4, gridspork/0.0.4

In the source

  • application/src/main/java/org/unigrid/hedgehog/server/rest/RestServer.java: starts the HTTPS listener and lists every resource class.
  • application/src/main/java/org/unigrid/hedgehog/server/rest/BearerTokenFilter.java: the token check.
  • application/src/main/java/org/unigrid/hedgehog/server/rest/GridSporkResource.java: spork reading, co-signing and renewal; the other spork resources sit in the same package.
  • application/src/main/java/org/unigrid/hedgehog/server/rest/StorageResource.java: file storage by fingerprint.
  • application/src/main/java/org/unigrid/hedgehog/command/option/RestOptions.java: the command-line options.
  • application/src/main/java/org/unigrid/hedgehog/client/rest/RestClient.java: the client the CLI uses.
  • application/src/main/java/org/unigrid/hedgehog/command/CLI.java: the hedgehog cli subcommands.