Class VaultHosts

java.lang.Object
lol.trq.alts.vault.VaultHosts

public final class VaultHosts extends Object
The runtime's way to AVP hosts: alts.vault(). Each connect reaches a host by its locator, learns its key from discovery (GET /.well-known/avp, SPEC 11.7) and, whenever the key is known beforehand, refuses a host that serves another one. Pass the known key every time there is one: discovery is unauthenticated, so a host reached by its locator alone is whoever answers there, and the key is what identifies a host (SPEC 3.3). The forms that take a RepoLocator, a HostRef, a VaultSnapshot or an explicit key all pass it; connectFirstContact(String) is the first contact with a host whose key nobody vouched for yet. A vault opened through any connection still requires the verified manifest state to list that host's key, and the member's home host to be that key.

A locator (host or host:port) is reached at https://<locator> unless the host set another mapping with AltsRuntime.Builder#vaultHostAddress. The mapped address's scheme picks the transport profile: https or http is HTTP/JSON over the runtime's transport, grpcs or grpc the gRPC profile over the VaultRpcChannel that AltsRuntime.Builder#vaultRpcChannel supplies for that address. Both profiles carry the same operations and are verified the same way. Every connection shares the runtime's transport and its token cache, which AltsRuntime#close() clears; a token is kept per host key, address and profile.

Every future fails only with an AltsException: PROTOCOL for a host that serves no key or another key than expected, INVALID_INPUT for a locator that is not host or host:port, a mapping that gives no http, https, grpc or grpcs URL, or a channel factory that throws or returns null, NOT_CONFIGURED for a gRPC address without a channel factory, NETWORK for a host that cannot be reached, and CANCELLED once the runtime is closed.

Since:
1.0.0
  • Method Details

    • connect

      public CompletableFuture<VaultHost> connect(RepoLocator locator)
      Connects to the owner's home host named by a repo locator, by the key it carries.
      Parameters:
      locator - the owner's repo locator
      Returns:
      the connection
      Since:
      1.0.0
    • connect

      public CompletableFuture<VaultHost> connect(HostRef host)
      Connects to a host of a repository, by its key.
      Parameters:
      host - a host from SharedVault.hosts()
      Returns:
      the connection
      Since:
      1.0.0
    • connect

      public CompletableFuture<VaultHost> connect(VaultSnapshot snapshot)
      Connects to the home host a snapshot names, by its key: the connection SharedVault.resume(VaultHost, OwnerIdentity, VaultSnapshot) needs.
      Parameters:
      snapshot - the persisted snapshot
      Returns:
      the connection
      Since:
      1.0.0
    • connect

      public CompletableFuture<VaultHost> connect(String locator, String hostKey)
      Connects to a host whose key is known from elsewhere, for example from the host's own published key.
      Parameters:
      locator - host or host:port
      hostKey - the host key the host must serve, base64
      Returns:
      the connection
      Since:
      1.0.0
    • connectFirstContact

      public CompletableFuture<VaultHost> connectFirstContact(String locator)
      Connects to a host by its locator alone, taking whatever key its discovery serves: the first contact with a host nobody vouched for, such as the home host an owner creates a repository on or the one a joiner picks for itself. Discovery is unauthenticated, so the resulting VaultHost.hostKey() is unverified: show it to the user or compare it out of band with the key the host publishes before trusting it. Persist VaultHost.ref() and reconnect later with connect(HostRef) or connect(String, String), which pin that key; prefer a form that passes a known key whenever one exists.
      Parameters:
      locator - host or host:port
      Returns:
      the connection
      Since:
      1.0.0
    • toString

      public String toString()
      Counts only.
      Overrides:
      toString in class Object
      Returns:
      a description
      Since:
      1.0.0