pub struct Client { /* private fields */ }Expand description
A handle on one Town OS box.
Cloning is cheap and shares the token, so a clone handed to a background task keeps working after the UI thread re-authenticates.
Implementations§
Source§impl Client
impl Client
Sourcepub async fn dns_status(&self) -> Result<DnsStatus>
pub async fn dns_status(&self) -> Result<DnsStatus>
Calls GET /dns/status.
Sourcepub async fn dns_records(&self, tld: Option<&str>) -> Result<Vec<DnsRecord>>
pub async fn dns_records(&self, tld: Option<&str>) -> Result<Vec<DnsRecord>>
Lists records, optionally confined to one TLD.
With no TLD this spans every network — the global home zone plus each network’s scoped zone — and each row says which it came from.
Calls GET /dns/records.
Sourcepub async fn add_dns_record(
&self,
name: &str,
record_type: RecordType,
value: &str,
ttl: u32,
) -> Result<()>
pub async fn add_dns_record( &self, name: &str, record_type: RecordType, value: &str, ttl: u32, ) -> Result<()>
Calls POST /dns/records/add (admin).
Sourcepub async fn remove_dns_record(
&self,
name: &str,
record_type: RecordType,
) -> Result<()>
pub async fn remove_dns_record( &self, name: &str, record_type: RecordType, ) -> Result<()>
Calls POST /dns/records/remove (admin).
Sourcepub async fn set_dns_tld(&self, tld: &str) -> Result<()>
pub async fn set_dns_tld(&self, tld: &str) -> Result<()>
Calls POST /dns/tld (admin).
Sourcepub async fn setup_dns(&self) -> Result<()>
pub async fn setup_dns(&self) -> Result<()>
Idempotent zone init plus package registration. Calls POST /dns/setup.
Sourcepub async fn dns_services(&self) -> Result<Vec<DnsService>>
pub async fn dns_services(&self) -> Result<Vec<DnsService>>
Calls GET /dns/services.
Sourcepub async fn set_dns_service(
&self,
repo: &str,
name: &str,
published: bool,
) -> Result<()>
pub async fn set_dns_service( &self, repo: &str, name: &str, published: bool, ) -> Result<()>
Publishes or withdraws a package service in the zone.
Calls POST /dns/services/set (admin).
Sourcepub async fn blocklist_config(
&self,
which: Blocklist,
) -> Result<BlocklistConfig>
pub async fn blocklist_config( &self, which: Blocklist, ) -> Result<BlocklistConfig>
Calls GET /dns/rbl or GET /dns/dnsbl.
Sourcepub async fn set_blocklist_config(
&self,
which: Blocklist,
enabled: bool,
providers: &[BlocklistProvider],
refusal_cooldown_secs: u64,
) -> Result<()>
pub async fn set_blocklist_config( &self, which: Blocklist, enabled: bool, providers: &[BlocklistProvider], refusal_cooldown_secs: u64, ) -> Result<()>
Replaces a blocklist’s configuration wholesale.
Calls POST /dns/rbl or POST /dns/dnsbl (admin).
Sourcepub async fn local_rbl(&self) -> Result<Vec<BlocklistEntry>>
pub async fn local_rbl(&self) -> Result<Vec<BlocklistEntry>>
Calls GET /dns/rbl/local.
Sourcepub async fn add_local_rbl(&self, name: &str, reason: &str) -> Result<()>
pub async fn add_local_rbl(&self, name: &str, reason: &str) -> Result<()>
Calls POST /dns/rbl/local/add (admin).
Sourcepub async fn remove_local_rbl(&self, name: &str) -> Result<()>
pub async fn remove_local_rbl(&self, name: &str) -> Result<()>
Calls POST /dns/rbl/local/remove (admin).
Sourcepub async fn dnsbl_allowlist(&self) -> Result<Vec<BlocklistEntry>>
pub async fn dnsbl_allowlist(&self) -> Result<Vec<BlocklistEntry>>
Names exempted from the name-based block, along with everything beneath
them. Calls GET /dns/dnsbl/allowlist.
Sourcepub async fn add_dnsbl_allowlist(&self, name: &str, reason: &str) -> Result<()>
pub async fn add_dnsbl_allowlist(&self, name: &str, reason: &str) -> Result<()>
Calls POST /dns/dnsbl/allowlist/add (admin).
Sourcepub async fn remove_dnsbl_allowlist(&self, name: &str) -> Result<()>
pub async fn remove_dnsbl_allowlist(&self, name: &str) -> Result<()>
Calls POST /dns/dnsbl/allowlist/remove (admin).
Source§impl Client
impl Client
Sourcepub async fn connected_peers(&self) -> Result<Vec<ConnectedPeer>>
pub async fn connected_peers(&self) -> Result<Vec<ConnectedPeer>>
Every peer across every overlay, joined with kernel state (admin only).
Calls GET /networks/peers/connected.
Sourcepub async fn add_peer(
&self,
network: &str,
name: &str,
public_key: Option<&str>,
endpoint: &str,
) -> Result<Enrollment>
pub async fn add_peer( &self, network: &str, name: &str, public_key: Option<&str>, endpoint: &str, ) -> Result<Enrollment>
Enrolls a device.
Pass public_key to keep the private half local; pass None to let the
server generate the pair and hand back the private key in
Enrollment::private_key.
endpoint is where other peers should dial this one, host:port. Empty
is right for a laptop behind NAT — it dials out and the box learns the
address from the handshake — and wrong for a machine that is supposed to
be reachable, which needs a name or address that resolves from the
overlay. validate_endpoint is the same check the box applies.
Calls POST /networks/peers/add. Permitted for an administrator or an
account holding the wireguard grant on this network.
Sourcepub async fn refresh_peer(
&self,
network: &str,
public_key: &str,
) -> Result<RefreshedPeer>
pub async fn refresh_peer( &self, network: &str, public_key: &str, ) -> Result<RefreshedPeer>
Slides this peer’s TTL forward — the heartbeat that keeps a long-lived enrollment alive. The server computes the new expiry; the caller does not choose it.
Calls POST /networks/peers/refresh.
Sourcepub async fn remove_peer(&self, network: &str, public_key: &str) -> Result<()>
pub async fn remove_peer(&self, network: &str, public_key: &str) -> Result<()>
Calls POST /networks/peers/remove (admin).
Sourcepub async fn enable_network(&self, name: &str) -> Result<()>
pub async fn enable_network(&self, name: &str) -> Result<()>
Calls POST /networks/enable (admin). Brings the overlay’s interface up.
Sourcepub async fn disable_network(&self, name: &str) -> Result<()>
pub async fn disable_network(&self, name: &str) -> Result<()>
Calls POST /networks/disable (admin). Takes the overlay down; local DNS
and services keep running.
Source§impl Client
impl Client
Sourcepub async fn ping(&self) -> Result<Ping>
pub async fn ping(&self) -> Result<Ping>
The dashboard counters.
Unauthenticated — the control plane answers this without a token so a
client can tell a reachable box from an unreachable one before asking for
a password. needs_setup says the box has no enabled administrator yet.
Calls GET /status/ping.
Sourcepub async fn system_services(&self) -> Result<Vec<SystemService>>
pub async fn system_services(&self) -> Result<Vec<SystemService>>
Calls GET /system-services.
Source§impl Client
impl Client
Sourcepub async fn partitions(&self) -> Result<Vec<Partition>>
pub async fn partitions(&self) -> Result<Vec<Partition>>
Lists every partition with its published names and live state.
Answers an empty list when object storage is not configured, which is a deployment choice rather than a failure — the UI says so instead of showing an error.
Calls GET /gfeh.
Sourcepub async fn principals(&self, network: &str) -> Result<Vec<Principal>>
pub async fn principals(&self, network: &str) -> Result<Vec<Principal>>
Calls GET /gfeh/principals.
Sourcepub async fn add_principal(
&self,
network: &str,
principal: &str,
) -> Result<Principal>
pub async fn add_principal( &self, network: &str, principal: &str, ) -> Result<Principal>
Projects a Town OS account into a partition.
The ceiling follows the account: an administrator becomes a gfeh superuser, anyone else gets read-write and no grants — deliberately useless until somebody grants them something.
Calls POST /gfeh/principals/add.
Sourcepub async fn remove_principal(
&self,
network: &str,
principal: &str,
) -> Result<()>
pub async fn remove_principal( &self, network: &str, principal: &str, ) -> Result<()>
Removes a principal, and with it every grant derived from it.
Calls POST /gfeh/principals/remove.
Sourcepub async fn grants(&self, network: &str, principal: &str) -> Result<Vec<Grant>>
pub async fn grants(&self, network: &str, principal: &str) -> Result<Vec<Grant>>
Lists what one principal holds. The principal is required — gfehd’s own handler has no default, so an absent one is an error rather than “every grant”.
Calls GET /gfeh/grants.
Sourcepub async fn add_grant(
&self,
network: &str,
principal: &str,
path: &str,
perm: &[String],
inheritable: bool,
) -> Result<Grant>
pub async fn add_grant( &self, network: &str, principal: &str, path: &str, perm: &[String], inheritable: bool, ) -> Result<Grant>
Grants a principal authority over a subtree.
The answer carries the rights as stored, which is what gfeh clamped them to rather than what was asked for. Callers must show that, not the request: an administrator has to be able to see a grant was narrowed, or they will believe they gave access nobody has.
Calls POST /gfeh/grants/add.
Sourcepub async fn revoke_grant(&self, network: &str, id: i64) -> Result<()>
pub async fn revoke_grant(&self, network: &str, id: i64) -> Result<()>
Calls POST /gfeh/grants/revoke.
Sourcepub async fn exposures(&self, network: &str) -> Result<Vec<Exposure>>
pub async fn exposures(&self, network: &str) -> Result<Vec<Exposure>>
Calls GET /gfeh/exposures.
Sourcepub async fn withdraw_exposure(&self, network: &str, token: &str) -> Result<()>
pub async fn withdraw_exposure(&self, network: &str, token: &str) -> Result<()>
Withdraws a published link, after which it stops resolving.
Calls POST /gfeh/exposures/withdraw.
Sourcepub async fn filesystems(
&self,
prefix: &str,
state: Option<&str>,
limit: u32,
offset: u32,
search: &str,
) -> Result<FilesystemPage>
pub async fn filesystems( &self, prefix: &str, state: Option<&str>, limit: u32, offset: u32, search: &str, ) -> Result<FilesystemPage>
Lists subvolumes. state filters to user, installed or
uninstalled; None spans all three.
Calls POST /storage.
Sourcepub async fn create_filesystem(&self, fs: &Filesystem) -> Result<()>
pub async fn create_filesystem(&self, fs: &Filesystem) -> Result<()>
Calls POST /storage/create.
Sourcepub async fn modify_filesystem(&self, name: &str, fs: &Filesystem) -> Result<()>
pub async fn modify_filesystem(&self, name: &str, fs: &Filesystem) -> Result<()>
Changes a volume’s name or quota.
Renaming works only for user volumes; a package volume (one under
installed/ or uninstalled/) must keep its name, and the server
refuses the call if fs.name differs from name.
Calls POST /storage/modify.
Sourcepub async fn remove_filesystem(&self, name: &str) -> Result<()>
pub async fn remove_filesystem(&self, name: &str) -> Result<()>
Calls POST /storage/remove.
Sourcepub async fn upload_archive(
&self,
subvolume: &str,
archive: &Path,
subpath: &str,
stop_service: &str,
) -> Result<ArchiveUpload>
pub async fn upload_archive( &self, subvolume: &str, archive: &Path, subpath: &str, stop_service: &str, ) -> Result<ArchiveUpload>
Unpacks an archive into a volume.
The file is streamed from disk rather than read into memory — these run to
a gigabyte by default — and its name matters: the box picks the
decompressor from the extension, so is_supported_archive is worth
checking before spending the upload.
subpath extracts into a subdirectory of the volume instead of its root.
stop_service names a systemd unit to stop for the duration, which is how
you replace files something is holding open; the box restarts it after.
Calls POST /storage/upload-archive (admin).
Sourcepub async fn download_archive(
&self,
subvolume: &str,
paths: &[String],
format: &str,
destination: &Path,
) -> Result<u64>
pub async fn download_archive( &self, subvolume: &str, paths: &[String], format: &str, destination: &Path, ) -> Result<u64>
Writes a compressed archive of a volume to destination.
paths confines the archive to those entries, relative to the volume
root; empty takes everything. format is one of ARCHIVE_FORMATS, or
empty for the box’s default.
The body is written to disk as it arrives, so this holds no more than one chunk in memory however large the volume is. A failure part way through leaves a partial file behind, which the caller should remove — an archive that stops in the middle is not a smaller archive.
Calls POST /storage/download-archive (admin).
Source§impl Client
impl Client
Sourcepub fn new(base: &str) -> Result<Self>
pub fn new(base: &str) -> Result<Self>
Builds a client for base (anything base_url_for accepts).
pub fn base_url(&self) -> &str
pub fn set_token(&self, token: impl Into<String>)
pub fn clear_token(&self)
pub fn token(&self) -> Option<String>
pub fn has_token(&self) -> bool
Sourcepub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T>
pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T>
GET path, decoding the JSON body.
Sourcepub async fn post_json<B: Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T>
pub async fn post_json<B: Serialize, T: DeserializeOwned>( &self, path: &str, body: &B, ) -> Result<T>
POST body to path, decoding the JSON answer.
Sourcepub async fn post_empty<B: Serialize>(&self, path: &str, body: &B) -> Result<()>
pub async fn post_empty<B: Serialize>(&self, path: &str, body: &B) -> Result<()>
POST body to path, discarding the answer.
Several endpoints answer {"status":"ok"} and several answer nothing at
all; neither is worth a type.
Sourcepub async fn authenticate(
&self,
username: &str,
password: &str,
) -> Result<Authenticated>
pub async fn authenticate( &self, username: &str, password: &str, ) -> Result<Authenticated>
Exchanges credentials for a session token, and stores it on this client.
Calls POST /account/authenticate.
Sourcepub async fn whoami(&self) -> Result<String>
pub async fn whoami(&self) -> Result<String>
Returns the username the current token belongs to.
Doubles as the token liveness check on startup: a stored token that has expired fails here, which is how the app knows to ask for a password again rather than showing an empty dashboard.
Calls GET /account/me.
Sourcepub async fn sessions(&self) -> Result<Vec<Session>>
pub async fn sessions(&self) -> Result<Vec<Session>>
Lists the account’s active sessions. Calls GET /account/sessions.
Sourcepub async fn revoke_session(&self, session_id: &str) -> Result<()>
pub async fn revoke_session(&self, session_id: &str) -> Result<()>
Invalidates a session by id. Calls POST /account/session/revoke.
The id is required. The box has no “revoke whichever session you are
calling from” spelling — an empty id is a 403 for an ordinary account and
a no-op for an administrator — so signing out uses
Client::current_session_id to name the session it is ending.
Sourcepub fn current_session_id(&self) -> Option<String>
pub fn current_session_id(&self) -> Option<String>
The id of the session this client holds a token for.
Read out of the token rather than fetched: the box issues a JWT carrying
session_id, and GET /account/sessions returns every session for the
account with nothing marking which one is calling — so the token is the
only place the answer exists.
The signature is deliberately not checked. This reads a claim out of a credential the box gave us to decide which id to name in a request the box will authorize on its own terms; nothing is trusted on the strength of it.
Sourcepub async fn account(&self, username: &str) -> Result<Account>
pub async fn account(&self, username: &str) -> Result<Account>
Returns the signed-in account, including its grants.
The UI reads admin and the grant list to decide which controls to
disable, so a non-admin sees why an action is unavailable instead of
discovering it through a 403.
Calls POST /account.
Sourcepub async fn set_password(
&self,
username: &str,
password: &str,
) -> Result<Account>
pub async fn set_password( &self, username: &str, password: &str, ) -> Result<Account>
Changes an account’s password.
Permitted on your own account without being an administrator, which is the
only reason this is worth having in a desktop client. The box requires at
least MIN_PASSWORD_LENGTH characters.
Calls POST /account/update.