Class AltsRuntime.Builder<H>
- Type Parameters:
H- the host's opaque texture-handle type
- Enclosing class:
AltsRuntime<H>
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaccountEndpoints(AccountEndpoints value) Points the account services and the profile lookup at another base (optional; by default they reach the origin of the configuredMicrosoftAuthConfig.minecraftProfileUrl(), or the public Minecraft services when Microsoft login is not configured).avatarSource(AvatarSource value) Sets the avatar source (optional; defaults to one that resolves the face from Mojang's session server and crops it locally).avatarUrlTemplate(String value) Fetches avatars from a head-render service by filling a URL template (optional; off by default).build()Validates the required seams, constructs the runtime, opens and locks its two store files in the directory thevaultDirectoryprovider names (asked once, here), and loads them — soAltsRuntime.store()is populated as soon as this returns.Sets the executor this runtime runs its blocking work on (optional; by default the runtime creates one that starts a virtual thread per task, namedalts-io-<n>, so a request parked on a slow endpoint holds no platform thread).gameStatsSource(GameStatsSource value) Registers a game-stats source for one server (optional; callable once per server).mainThread(MainThreadExecutor value) Sets the main-thread executor (required).microsoftAuth(MicrosoftAuthConfig value) Sets the Microsoft authentication configuration (optional; without it Microsoft login fails cleanly while offline / cookie / session login stay available).migrateFromMachineKey(boolean value) Sets whether stores written before astoreKeyProviderwas installed are migrated to it (optional; off by default).proxyProvider(ProxyProvider value) Sets the proxy provider (optional; without one every request connects directly, as in every release before this seam existed).secretsFileName(String value) Overrides the on-disk secret-store filename (optional; defaults to a neutral name).secretsKeyBinding(String value) Overrides the key-binding constant mixed into the secret-store encryption key (optional; defaults to a neutral constant).sessionInjector(SessionInjector value) Sets the session injector (required).storeFileName(String value) Overrides the on-disk store filename (optional; defaults to a neutral name).storeKeyBinding(String value) Overrides the key-binding constant mixed into the storage encryption key (optional; defaults to a neutral constant).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).textureUploader(TextureUploader<H> value) Sets the texture uploader (optional; avatars degrade to the initial-letter fallback if absent).Sets the toast sink (required).Sets the vault directory provider (required).vaultHostAddress(Function<String, URI> value) Maps an AVP host locator (hostorhost:port, as tokens and manifests name a host) to the base URLAltsRuntime.vault()reaches it at (optional; by defaulthttps://<locator>).vaultRpcChannel(Function<URI, VaultRpcChannel> value) Supplies the gRPC channel for a vault host mapped to agrpc://orgrpcs://address (optional).
-
Constructor Details
-
Builder
public Builder()Creates an empty builder; populate it with the host seams, then callbuild().- Since:
- 0.1.0
-
-
Method Details
-
sessionInjector
Sets the session injector (required).- Parameters:
value- the host session injector- Returns:
- this builder
- Since:
- 0.1.0
-
vaultDirectory
Sets the vault directory provider (required). It is asked once, bybuild(), 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
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
Sets the main-thread executor (required).- Parameters:
value- the host main-thread executor- Returns:
- this builder
- Since:
- 0.1.0
-
toastSink
Sets the toast sink (required).- Parameters:
value- the host toast sink- Returns:
- this builder
- Since:
- 0.1.0
-
gameStatsSource
Registers a game-stats source for one server (optional; callable once per server). Without any source,AltsRuntime.gameStats(String)always returns null. The source'sGameStatsSource.serverId()is the key consumers pass togameStats(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
Sets the Microsoft authentication configuration (optional; without it Microsoft login fails cleanly while offline / cookie / session login stay available). TheclientIdinside 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
Maps an AVP host locator (hostorhost:port, as tokens and manifests name a host) to the base URLAltsRuntime.vault()reaches it at (optional; by defaulthttps://<locator>). For a host that reaches vault hosts through a gateway, or a development host served over plainhttpon 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 withAltsFailure.Kind.INVALID_INPUT.- Parameters:
value- the mapping, or null for the default- Returns:
- this builder
- Since:
- 1.0.0
-
vaultRpcChannel
Supplies the gRPC channel for a vault host mapped to agrpc://orgrpcs://address (optional). The schemevaultHostAddressmaps a locator to chooses the transport profile: anhttpsorhttpaddress is reached over HTTP/JSON through the runtime's own transport, agrpcsorgrpcaddress over the gRPC profile through theVaultRpcChannelthis factory returns for it. The library ships no gRPC client: without a factory, a gRPC address fails its connection withAltsFailure.Kind.NOT_CONFIGURED, and a factory that throws or returns null fails it withAltsFailure.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'sexecutor: a bounded executor shared with the channel's or its tunnel's callbacks stalls calls (seeVaultRpcChannel).- Parameters:
value- the channel factory, called with the mapped address, or null for none- Returns:
- this builder
- Since:
- 1.1.0
-
avatarSource
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 setavatarUrlTemplate(String)rather than implement this. Setting both failsbuild().- Parameters:
value- the host avatar source- Returns:
- this builder
- Since:
- 0.10.0
-
avatarUrlTemplate
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 examplehttps://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 purposeAVATAR.build()fails when the template has no{uuid}placeholder, or when anavatarSourceis also set.- Parameters:
value- the URL template, or null for none- Returns:
- this builder
- Since:
- 1.0.0
-
accountEndpoints
Points the account services and the profile lookup at another base (optional; by default they reach the origin of the configuredMicrosoftAuthConfig.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
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
Sets the executor this runtime runs its blocking work on (optional; by default the runtime creates one that starts a virtual thread per task, namedalts-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 byAltsRuntime.close(). A vault call over avaultRpcChannelwaits 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
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
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
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
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
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 unlessmigrateFromMachineKey(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
Sets whether stores written before astoreKeyProviderwas 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
Validates the required seams, constructs the runtime, opens and locks its two store files in the directory thevaultDirectoryprovider names (asked once, here), and loads them — soAltsRuntime.store()is populated as soon as this returns. A file that exists but cannot be read leaves the list alone and is reported onAccountStore.loadError(). Whatever the reason (thestoreKeyProvidercould not supply its key, the file is sealed under another key, or it is damaged), nothing is written over that file until a laterAccountStore.load()succeeds or the host callsAccountStore.discardUnreadable()(and the same onHostSecrets).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
AltsExceptionof kindAltsFailure.Kind.CONFLICTsaying 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 kindAltsFailure.Kind.STORAGE.- Returns:
- the constructed runtime, which the host closes when done with it
- Throws:
NullPointerException- if a required seam is missingAltsException- of kindAltsFailure.Kind.CONFLICTif a store file is in use by another runtime, orAltsFailure.Kind.STORAGEif one cannot be locked- Since:
- 0.1.0
-