Skip to main content

Client

Struct Client 

Source
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

Source

pub async fn dns_status(&self) -> Result<DnsStatus>

Calls GET /dns/status.

Source

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.

Source

pub async fn add_dns_record( &self, name: &str, record_type: RecordType, value: &str, ttl: u32, ) -> Result<()>

Calls POST /dns/records/add (admin).

Source

pub async fn remove_dns_record( &self, name: &str, record_type: RecordType, ) -> Result<()>

Calls POST /dns/records/remove (admin).

Source

pub async fn dns_tld(&self) -> Result<String>

Calls GET /dns/tld.

Source

pub async fn set_dns_tld(&self, tld: &str) -> Result<()>

Calls POST /dns/tld (admin).

Source

pub async fn setup_dns(&self) -> Result<()>

Idempotent zone init plus package registration. Calls POST /dns/setup.

Source

pub async fn dns_services(&self) -> Result<Vec<DnsService>>

Calls GET /dns/services.

Source

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).

Source

pub async fn blocklist_config( &self, which: Blocklist, ) -> Result<BlocklistConfig>

Calls GET /dns/rbl or GET /dns/dnsbl.

Source

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).

Source

pub async fn local_rbl(&self) -> Result<Vec<BlocklistEntry>>

Calls GET /dns/rbl/local.

Source

pub async fn add_local_rbl(&self, name: &str, reason: &str) -> Result<()>

Calls POST /dns/rbl/local/add (admin).

Source

pub async fn remove_local_rbl(&self, name: &str) -> Result<()>

Calls POST /dns/rbl/local/remove (admin).

Source

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.

Source

pub async fn add_dnsbl_allowlist(&self, name: &str, reason: &str) -> Result<()>

Calls POST /dns/dnsbl/allowlist/add (admin).

Source

pub async fn remove_dnsbl_allowlist(&self, name: &str) -> Result<()>

Calls POST /dns/dnsbl/allowlist/remove (admin).

Source§

impl Client

Source

pub async fn networks(&self) -> Result<Vec<Network>>

Calls GET /networks.

Source

pub async fn peers(&self, network: &str) -> Result<Vec<Peer>>

Calls GET /networks/peers.

Source

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.

Source

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.

Source

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.

Source

pub async fn remove_peer(&self, network: &str, public_key: &str) -> Result<()>

Calls POST /networks/peers/remove (admin).

Source

pub async fn enable_network(&self, name: &str) -> Result<()>

Calls POST /networks/enable (admin). Brings the overlay’s interface up.

Source

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

Source

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.

Source

pub async fn system_services(&self) -> Result<Vec<SystemService>>

Calls GET /system-services.

Source

pub async fn set_system_service(&self, key: &str, action: &str) -> Result<()>

Starts, stops or restarts a core service.

Calls POST /system-services/status (admin).

Source§

impl Client

Source

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.

Source

pub async fn principals(&self, network: &str) -> Result<Vec<Principal>>

Calls GET /gfeh/principals.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn revoke_grant(&self, network: &str, id: i64) -> Result<()>

Calls POST /gfeh/grants/revoke.

Source

pub async fn exposures(&self, network: &str) -> Result<Vec<Exposure>>

Calls GET /gfeh/exposures.

Source

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.

Source

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.

Source

pub async fn create_filesystem(&self, fs: &Filesystem) -> Result<()>

Calls POST /storage/create.

Source

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.

Source

pub async fn remove_filesystem(&self, name: &str) -> Result<()>

Calls POST /storage/remove.

Source

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).

Source

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

Source

pub fn new(base: &str) -> Result<Self>

Builds a client for base (anything base_url_for accepts).

Source

pub fn base_url(&self) -> &str

Source

pub fn set_token(&self, token: impl Into<String>)

Source

pub fn clear_token(&self)

Source

pub fn token(&self) -> Option<String>

Source

pub fn has_token(&self) -> bool

Source

pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T>

GET path, decoding the JSON body.

Source

pub async fn post_json<B: Serialize, T: DeserializeOwned>( &self, path: &str, body: &B, ) -> Result<T>

POST body to path, decoding the JSON answer.

Source

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.

Source

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.

Source

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.

Source

pub async fn sessions(&self) -> Result<Vec<Session>>

Lists the account’s active sessions. Calls GET /account/sessions.

Source

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.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Client

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more