Class AltsRuntime.Builder<H>

java.lang.Object
lol.trq.alts.AltsRuntime.Builder<H>
Type Parameters:
H - the host's opaque texture-handle type
Enclosing class:
AltsRuntime<H>

public static final class AltsRuntime.Builder<H> extends Object
Accumulating builder that injects the host seams. Required seams are validated in build(), never in the setters; setters use bare names (no withX prefixes).
Since:
0.1.0
  • Constructor Details

    • Builder

      public Builder()
      Creates an empty builder; populate it with the host seams, then call build().
      Since:
      0.1.0
  • Method Details

    • sessionInjector

      public AltsRuntime.Builder<H> sessionInjector(SessionInjector value)
      Sets the session injector (required).
      Parameters:
      value - the host session injector
      Returns:
      this builder
      Since:
      0.1.0
    • vaultDirectory

      public AltsRuntime.Builder<H> vaultDirectory(VaultDirectoryProvider value)
      Sets the vault directory provider (required). It is asked once, by build(), and the runtime's two store files live in that directory for the runtime's lifetime.
      Parameters:
      value - the host vault directory provider
      Returns:
      this builder
      Since:
      0.1.0
    • textureUploader

      public AltsRuntime.Builder<H> textureUploader(TextureUploader<H> value)
      Sets the texture uploader (optional; avatars degrade to the initial-letter fallback if absent).
      Parameters:
      value - the host texture uploader
      Returns:
      this builder
      Since:
      0.1.0
    • mainThread

      public AltsRuntime.Builder<H> mainThread(MainThreadExecutor value)
      Sets the main-thread executor (required).
      Parameters:
      value - the host main-thread executor
      Returns:
      this builder
      Since:
      0.1.0
    • toastSink

      public AltsRuntime.Builder<H> toastSink(ToastSink value)
      Sets the toast sink (required).
      Parameters:
      value - the host toast sink
      Returns:
      this builder
      Since:
      0.1.0
    • gameStatsSource

      public AltsRuntime.Builder<H> gameStatsSource(GameStatsSource value)
      Registers a game-stats source for one server (optional; callable once per server). Without any source, AltsRuntime.gameStats(String) always returns null. The source's GameStatsSource.serverId() is the key consumers pass to gameStats(serverId).
      Parameters:
      value - the host game-stats source
      Returns:
      this builder
      Throws:
      IllegalStateException - if a source for the same server id was already registered
      Since:
      0.3.0
    • microsoftAuth

      public AltsRuntime.Builder<H> microsoftAuth(MicrosoftAuthConfig value)
      Sets the Microsoft authentication configuration (optional; without it Microsoft login fails cleanly while offline / cookie / session login stay available). The clientId inside is the host's own Azure app id — the library ships no default.
      Parameters:
      value - the host Microsoft authentication configuration
      Returns:
      this builder
      Since:
      0.2.0
    • vaultHostAddress

      public AltsRuntime.Builder<H> vaultHostAddress(Function<String,URI> value)
      Maps an AVP host locator (host or host:port, as tokens and manifests name a host) to the base URL AltsRuntime.vault() reaches it at (optional; by default https://<locator>). For a host that reaches vault hosts through a gateway, or a development host served over plain http on a trusted network. The mapping never changes which host is accepted: a host is matched by its key wherever it is reached, and a token is kept per host key and address. A mapping that throws or returns null fails that connection with AltsFailure.Kind.INVALID_INPUT.
      Parameters:
      value - the mapping, or null for the default
      Returns:
      this builder
      Since:
      1.0.0
    • vaultRpcChannel

      public AltsRuntime.Builder<H> vaultRpcChannel(Function<URI, VaultRpcChannel> value)
      Supplies the gRPC channel for a vault host mapped to a grpc:// or grpcs:// address (optional). The scheme vaultHostAddress maps a locator to chooses the transport profile: an https or http address is reached over HTTP/JSON through the runtime's own transport, a grpcs or grpc address over the gRPC profile through the VaultRpcChannel this factory returns for it. The library ships no gRPC client: without a factory, a gRPC address fails its connection with AltsFailure.Kind.NOT_CONFIGURED, and a factory that throws or returns null fails it with AltsFailure.Kind.INVALID_INPUT.

      The factory runs at most once per mapped address per runtime, and the runtime keeps the channel it returns until it closes; it never closes a channel, whose lifecycle is the host's. A channel carries the bearer tokens the vault mints, and its routing and TLS are the host's to get right. Tokens stay apart per address and profile: one minted over HTTP is never sent over gRPC, even to the same host.

      The factory runs synchronously inside connect, under the compute of a concurrent map, so it must be quick (build or look up a channel, never dial and wait) and must not call back into this runtime. A channel's inbound message limit must be at least 16 MiB, and it must complete its futures from its own threads, never from a task on the runtime's executor: a bounded executor shared with the channel's or its tunnel's callbacks stalls calls (see VaultRpcChannel).

      Parameters:
      value - the channel factory, called with the mapped address, or null for none
      Returns:
      this builder
      Since:
      1.1.0
    • avatarSource

      public AltsRuntime.Builder<H> avatarSource(AvatarSource value)
      Sets the avatar source (optional; defaults to one that resolves the face from Mojang's session server and crops it locally). A host that wants a head-render service instead can set avatarUrlTemplate(String) rather than implement this. Setting both fails build().
      Parameters:
      value - the host avatar source
      Returns:
      this builder
      Since:
      0.10.0
    • avatarUrlTemplate

      public AltsRuntime.Builder<H> avatarUrlTemplate(String value)
      Fetches avatars from a head-render service by filling a URL template (optional; off by default). The template holds a {uuid} placeholder and optionally {size}, for example https://example.net/avatar/{uuid}/{size}.png; the UUID is passed as the caller gave it. This is a deliberate trade: it discloses each account's UUID to that service on every cache miss, which the default source exists to avoid. The fetch goes through the runtime's transport, so the proxy provider sees it with purpose AVATAR. build() fails when the template has no {uuid} placeholder, or when an avatarSource is also set.
      Parameters:
      value - the URL template, or null for none
      Returns:
      this builder
      Since:
      1.0.0
    • accountEndpoints

      public AltsRuntime.Builder<H> accountEndpoints(AccountEndpoints value)
      Points the account services and the profile lookup at another base (optional; by default they reach the origin of the configured MicrosoftAuthConfig.minecraftProfileUrl(), or the public Minecraft services when Microsoft login is not configured). For a host that fronts the Minecraft services with its own gateway, or a test pointing them at a loopback server.
      Parameters:
      value - the endpoints, or null for the default
      Returns:
      this builder
      Since:
      1.0.0
    • proxyProvider

      public AltsRuntime.Builder<H> proxyProvider(ProxyProvider value)
      Sets the proxy provider (optional; without one every request connects directly, as in every release before this seam existed). The library asks it per request, so any rotation policy — per-account pinning, round-robin, a health-checked pool — lives behind the host's implementation.

      Note that resolution fails closed when a provider is set: see ProxyProvider. The provider belongs to this runtime and is fixed for its lifetime: every request this runtime makes asks it, and no request of another runtime ever does. A runtime built without one connects directly, whatever another runtime in the process was given.

      Parameters:
      value - the host proxy provider, or null for direct connections
      Returns:
      this builder
      Since:
      0.8.0
    • executor

      public AltsRuntime.Builder<H> executor(Executor value)
      Sets the executor this runtime runs its blocking work on (optional; by default the runtime creates one that starts a virtual thread per task, named alts-io-<n>, so a request parked on a slow endpoint holds no platform thread). Install one to bound concurrency or to propagate the host's own context. Every request, cache load, avatar download and bulk entry of this runtime runs on it, and nothing of another runtime's does. The runtime never shuts a host's executor down; one it created itself is shut down by AltsRuntime.close(). A vault call over a vaultRpcChannel waits on one of this executor's threads, so the channel must complete its futures from its own threads, never from a task on this executor: a bounded executor that also runs the channel's or its tunnel's callbacks stalls those calls until their deadline.
      Parameters:
      value - the host executor, or null for one the runtime creates and owns
      Returns:
      this builder
      Since:
      0.12.0
    • storeFileName

      public AltsRuntime.Builder<H> storeFileName(String value)
      Overrides the on-disk store filename (optional; defaults to a neutral name). Hosts migrating from an earlier filename pass it here so existing files keep loading.
      Parameters:
      value - the store filename, or null/blank to keep the default
      Returns:
      this builder
      Since:
      0.1.0
    • storeKeyBinding

      public AltsRuntime.Builder<H> storeKeyBinding(String value)
      Overrides the key-binding constant mixed into the storage encryption key (optional; defaults to a neutral constant). Hosts migrating from an earlier constant pass it here so existing files keep decrypting. Changing it for an existing store renders prior files undecryptable.
      Parameters:
      value - the key-binding constant, or null/blank to keep the default
      Returns:
      this builder
      Since:
      0.1.0
    • secretsFileName

      public AltsRuntime.Builder<H> secretsFileName(String value)
      Overrides the on-disk secret-store filename (optional; defaults to a neutral name). The secret store holds per-user secrets separately from the shareable account store.
      Parameters:
      value - the secret-store filename, or null/blank to keep the default
      Returns:
      this builder
      Since:
      0.1.0
    • secretsKeyBinding

      public AltsRuntime.Builder<H> secretsKeyBinding(String value)
      Overrides the key-binding constant mixed into the secret-store encryption key (optional; defaults to a neutral constant). Changing it for an existing store renders prior secret files undecryptable.
      Parameters:
      value - the secret-store key-binding constant, or null/blank to keep the default
      Returns:
      this builder
      Since:
      0.1.0
    • storeKeyProvider

      public AltsRuntime.Builder<H> storeKeyProvider(StoreKeyProvider value)
      Sets the store key provider (optional; without one both encrypted stores are sealed under a key derived from machine properties, as in every release before this seam existed). A host that can reach a real secret, such as an operating-system keystore entry, supplies it here. A file written under a host key does not open without it, and a file written before the provider was installed does not open under it either unless migrateFromMachineKey(boolean) is on for that launch.

      Note that resolution fails closed once a provider is installed: see StoreKeyProvider. The provider belongs to this runtime's stores alone and is fixed for their lifetime; another runtime's provider never reaches them.

      Parameters:
      value - the host store key provider, or null for the machine-derived key
      Returns:
      this builder
      Since:
      0.12.0
    • migrateFromMachineKey

      public AltsRuntime.Builder<H> migrateFromMachineKey(boolean value)
      Sets whether stores written before a storeKeyProvider was installed are migrated to it (optional; off by default). While on, a store that does not open under the host's key but does under the machine-derived default is loaded and rewritten under the host's key, and every kept copy of it, the rolling backup included, is resealed or removed, so that no file left in the directory opens under the old key.

      Enable it for the upgrade launch only — the one that first installs the key provider over existing files — and leave it off from then on. While it is on, the machine-derived key is still accepted, so anyone able to write the store directory can plant a store sealed under that guessable key, or restore a copy from before the migration, and have it load. While it is off, a file that does not open under the host's key is reported on AccountStore.loadError() and left as it is. Has no effect without a key provider.

      Parameters:
      value - true to accept and reseal stores sealed under the machine-derived key
      Returns:
      this builder
      Since:
      0.12.0
    • build

      public AltsRuntime<H> build()
      Validates the required seams, constructs the runtime, opens and locks its two store files in the directory the vaultDirectory provider names (asked once, here), and loads them — so AltsRuntime.store() is populated as soon as this returns. A file that exists but cannot be read leaves the list alone and is reported on AccountStore.loadError(). Whatever the reason (the storeKeyProvider could not supply its key, the file is sealed under another key, or it is damaged), nothing is written over that file until a later AccountStore.load() succeeds or the host calls AccountStore.discardUnreadable() (and the same on HostSecrets).

      Each store file is locked for the runtime's lifetime. When another runtime, in this process or another, holds either file, this fails with an AltsException of kind AltsFailure.Kind.CONFLICT saying the store file is in use (the message names the file, not its path) and holds no lock afterwards; a directory that cannot be created or locked fails it with kind AltsFailure.Kind.STORAGE.

      Returns:
      the constructed runtime, which the host closes when done with it
      Throws:
      NullPointerException - if a required seam is missing
      AltsException - of kind AltsFailure.Kind.CONFLICT if a store file is in use by another runtime, or AltsFailure.Kind.STORAGE if one cannot be locked
      Since:
      0.1.0