//! SERVER ONLY. The Rust embed backend tool (EMBED_CONTRACT.md, "Backend tools"). It extends the
//! integration allocator (`rust/integration/server`, INTEGRATION_CONTRACT.md "Runnable backend
//! allocators") with the embed commands: provision an installation's client, set and read its data
//! caps, list every capped client, remove a client, set a client's ACL group (`acl <key>
//! default|isolated`), and read the network's Embed state (`status`). The authenticated backend
//! supplies each
//! `user:<service-user-id>[:<installation-id>]` key internally; never pass an untrusted request
//! field or a URnetwork client ID.
//!
//! Settings: `URNETWORK_ROOT_JWT` (an API key or a network JWT, from the backend secret store),
//! `URNETWORK_CLIENT_MAP` (absolute file path in an existing private, service-owned directory),
//! optional `URNETWORK_API_URL` and optional `URNETWORK_DEFAULT_ACL_GROUP` (the ACL group of each new
//! client: `isolated`, the default, or `default`). The map stores client IDs, never tokens; a
//! crash-left `<map>.lock` may be removed only after confirming that no tool still owns it.
//!
//! Exit codes: 0 success, 78 configuration or credential problem (missing settings, an invalid key
//! or map, the root credential refused, the client limit), 1 any other failure. Errors are one
//! stderr line that never contains a secret.
use base64::{
Engine, alphabet,
engine::{DecodePaddingMode, GeneralPurpose, GeneralPurposeConfig},
};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
#[cfg(unix)]
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
use std::{
collections::{BTreeMap, BTreeSet},
env,
fs::{self, OpenOptions},
io::{self, Read, Write},
path::{Path, PathBuf},
time::{Duration, SystemTime, UNIX_EPOCH},
};
/// The largest map file and API answer the tool reads.
const LIMIT: u64 = 1 << 20;
/// The description of every client the tool provisions. It is visible to URnetwork, so it names no
/// user: the map links each client to its key.
const DESCRIPTION: &str = "embed client";
/// The device spec of every client the tool provisions.
const DEVICE_SPEC: &str = "urnetwork-examples/rust-embed-server";
/// The stderr line for a refusal at either client limit.
const CLIENT_LIMIT_MESSAGE: &str =
"client limit reached: your network is at its client limit; see https://ur.io/services";
/// The API's message for a client that was removed or deactivated after 30 days without connecting.
const CLIENT_DOES_NOT_EXIST: &str = "Client does not exist.";
/// The largest byte count a cap takes.
const MAX_BYTE_COUNT: u64 = i64::MAX as u64;
/// The page size of `usage-all`.
const USAGE_ALL_PAGE_SIZE: &str = "1000";
/// The stderr line for `cap`, `usage`, `remove` or `acl` with a key that has no client.
const UNMAPPED_MESSAGE: &str = "no client is mapped for that key; run provision first";
/// The stderr line for a server without ACL groups.
const ACL_UNSUPPORTED_MESSAGE: &str =
"/network/client-acl-group answered 404: the server predates ACL groups";
/// The server refuses the data-cap and ACL-group routes with this message while the team has not
/// enabled Embed for the network (EMBED_CONTRACT.md, "Embed enablement"); caps and groups set
/// earlier stay enforced.
const EMBED_NOT_ENABLED_MESSAGE: &str = "Embed isn't enabled for this network.";
/// What `cap`, `usage`, `usage-all` and `acl` print for the refusal, with exit 78.
const EMBED_NOT_ENABLED_LINE: &str =
"embed not enabled: Embed isn't enabled for this network; see https://ur.io/services";
/// What `provision` prints on stderr when the client's default ACL group stays pending because
/// Embed isn't enabled, with exit 0.
const EMBED_PENDING_LINE: &str = "embed not enabled: the client's defaults stay pending until Embed is enabled; see https://ur.io/services";
const EMBED_UNSUPPORTED_MESSAGE: &str =
"/network/embed answered 404: the server predates Embed enablement";
const AUTH_CLIENT_PATH: &str = "/network/auth-client";
const CAP_PATH: &str = "/network/client-data-cap";
const CAPS_PATH: &str = "/network/client-data-caps";
const REMOVE_PATH: &str = "/network/remove-client";
const ACL_PATH: &str = "/network/client-acl-group";
const EMBED_PATH: &str = "/network/embed";
const ACL_GROUP_DEFAULT: &str = "default";
const ACL_GROUP_ISOLATED: &str = "isolated";
const EXIT_OK: i32 = 0;
const EXIT_FAILURE: i32 = 1;
const EXIT_CONFIG: i32 = 78;
const USAGE: &str = "usage: urnetwork-embed-server provision <key> <client-jwt-file> | cap <key> [--monthly <bytes>|null] [--total <bytes>|null] [--reset-total] | usage <key> | usage-all | remove <key> | acl <key> default|isolated | status | --self-test";
/// URL-safe base64 for JWT segments, accepting missing padding, as Go's decoder does.
const URL_SAFE_LENIENT: GeneralPurpose = GeneralPurpose::new(
&alphabet::URL_SAFE,
GeneralPurposeConfig::new()
.with_decode_padding_mode(DecodePaddingMode::Indifferent)
.with_decode_allow_trailing_bits(true),
);
/// The private client map: the allocators' format, plus `pending_acl`, the keys whose new clients
/// still owe their default ACL group, written only while it is not empty. A map with any other
/// field, such as the token server's `pending_caps`, is refused, so that two tools never rewrite
/// each other's map.
#[derive(Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct ClientMap {
version: u32,
clients: BTreeMap<String, String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pending_acl: Vec<String>,
}
impl ClientMap {
/// Records that the key's new client owes its default ACL group, or drops the record.
fn set_acl_pending(&mut self, key: &str, pending: bool) {
self.pending_acl.retain(|entry| entry != key);
if pending {
self.pending_acl.push(key.to_string());
}
}
/// Whether the key's client owes its default ACL group.
fn acl_pending(&self, key: &str) -> bool {
self.pending_acl.iter().any(|entry| entry == key)
}
}
/// Why a command failed: its exit code and one stderr line without a secret.
#[derive(Debug, PartialEq, Eq)]
enum ToolError {
/// Missing settings, an invalid key, map or argument, or the root credential refused: exit 78.
Config(String),
/// URnetwork refused a new client at the client limit: exit 78.
ClientLimit,
/// URnetwork refused a data-cap or ACL-group request because Embed isn't enabled: exit 78.
EmbedNotEnabled,
/// Any other failure: exit 1.
Failure(String),
}
impl ToolError {
/// The exit code.
fn exit_code(&self) -> i32 {
match self {
ToolError::Config(_) | ToolError::ClientLimit | ToolError::EmbedNotEnabled => {
EXIT_CONFIG
}
ToolError::Failure(_) => EXIT_FAILURE,
}
}
/// The stderr line.
fn message(&self) -> String {
match self {
ToolError::Config(message) | ToolError::Failure(message) => message.clone(),
ToolError::ClientLimit => CLIENT_LIMIT_MESSAGE.to_string(),
ToolError::EmbedNotEnabled => EMBED_NOT_ENABLED_LINE.to_string(),
}
}
}
/// A failure while writing the tool's own output.
impl From<io::Error> for ToolError {
fn from(error: io::Error) -> Self {
ToolError::Failure(format!("i/o error: {error}"))
}
}
/// A cap value from the command line: a byte count, or `null` to clear the cap.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum CapValue {
Bytes(u64),
Null,
}
impl CapValue {
/// The JSON value: an integer, or `null`.
fn to_json(self) -> Value {
match self {
CapValue::Bytes(byte_count) => json!(byte_count),
CapValue::Null => Value::Null,
}
}
}
/// What the arguments ask for.
#[derive(Debug, PartialEq, Eq)]
enum Command {
Provision {
key: String,
client_jwt_file: PathBuf,
},
Cap {
key: String,
monthly: Option<CapValue>,
total: Option<CapValue>,
reset_total: bool,
},
Usage {
key: String,
},
UsageAll,
Remove {
key: String,
},
Acl {
key: String,
group: &'static str,
},
Status,
SelfTest,
}
/// An ACL group named on the command line or in `URNETWORK_DEFAULT_ACL_GROUP`.
fn acl_group(text: &str) -> Option<&'static str> {
match text {
ACL_GROUP_DEFAULT => Some(ACL_GROUP_DEFAULT),
ACL_GROUP_ISOLATED => Some(ACL_GROUP_ISOLATED),
_ => None,
}
}
/// The ACL group of each new client from `URNETWORK_DEFAULT_ACL_GROUP`: `isolated` when it is unset
/// or empty.
fn default_acl_group(setting: Option<&str>) -> Result<&'static str, ToolError> {
match setting {
None | Some("") => Ok(ACL_GROUP_ISOLATED),
Some(text) => acl_group(text).ok_or_else(|| {
ToolError::Config("URNETWORK_DEFAULT_ACL_GROUP must be default or isolated".to_string())
}),
}
}
/// Whether a key matches the allocator pattern `user:[A-Za-z0-9][A-Za-z0-9_.:@-]{0,122}`, so both
/// `user:alice` and `user:alice:22222222-2222-2222-2222-222222222222` work.
fn key_valid(key: &str) -> bool {
let Some(rest) = key.strip_prefix("user:") else {
return false;
};
!rest.is_empty()
&& key.len() <= 128
&& rest.as_bytes()[0].is_ascii_alphanumeric()
&& rest
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b"_.:@-".contains(&b))
}
/// A valid key, or a configuration error.
fn checked_key(key: &str) -> Result<String, ToolError> {
if key_valid(key) {
Ok(key.to_string())
} else {
Err(ToolError::Config(
"invalid key: expected user:<service-user-id>[:<installation-id>]".to_string(),
))
}
}
/// Whether an id is a lowercase canonical UUID.
fn id_valid(id: &str) -> bool {
id.len() == 36
&& id.bytes().enumerate().all(|(i, b)| {
if [8, 13, 18, 23].contains(&i) {
b == b'-'
} else {
b.is_ascii_digit() || (b'a'..=b'f').contains(&b)
}
})
}
/// A cap option value: a decimal integer from 0 to 9223372036854775807 with no sign or units, or
/// `null`.
fn parse_cap_value(text: &str) -> Result<CapValue, ToolError> {
if text == "null" {
return Ok(CapValue::Null);
}
let invalid = || {
ToolError::Config(
"a cap is a decimal byte count from 0 to 9223372036854775807 with no units, or null"
.to_string(),
)
};
if text.is_empty() || !text.bytes().all(|b| b.is_ascii_digit()) {
return Err(invalid());
}
match text.parse::<u64>() {
Ok(byte_count) if byte_count <= MAX_BYTE_COUNT => Ok(CapValue::Bytes(byte_count)),
_ => Err(invalid()),
}
}
/// The command for the arguments after the program name.
fn parse_command(args: &[String]) -> Result<Command, ToolError> {
let usage = || ToolError::Config(USAGE.to_string());
let args: Vec<&str> = args.iter().map(String::as_str).collect();
match args.as_slice() {
["--self-test"] => Ok(Command::SelfTest),
["provision", key, client_jwt_file] => {
if client_jwt_file.is_empty() {
return Err(usage());
}
Ok(Command::Provision {
key: checked_key(key)?,
client_jwt_file: PathBuf::from(client_jwt_file),
})
}
["usage", key] => Ok(Command::Usage {
key: checked_key(key)?,
}),
["usage-all"] => Ok(Command::UsageAll),
["status"] => Ok(Command::Status),
["remove", key] => Ok(Command::Remove {
key: checked_key(key)?,
}),
["acl", key, group] => {
let group = acl_group(group).ok_or_else(usage)?;
Ok(Command::Acl {
key: checked_key(key)?,
group,
})
}
["cap", key, options @ ..] => {
let key = checked_key(key)?;
let (mut monthly, mut total, mut reset_total) = (None, None, false);
let mut index = 0;
while index < options.len() {
match options[index] {
"--monthly" if monthly.is_none() => {
let value = options.get(index + 1).ok_or_else(usage)?;
monthly = Some(parse_cap_value(value)?);
index += 2;
}
"--total" if total.is_none() => {
let value = options.get(index + 1).ok_or_else(usage)?;
total = Some(parse_cap_value(value)?);
index += 2;
}
"--reset-total" if !reset_total => {
reset_total = true;
index += 1;
}
_ => return Err(usage()),
}
}
if monthly.is_none() && total.is_none() && !reset_total {
return Err(usage());
}
Ok(Command::Cap {
key,
monthly,
total,
reset_total,
})
}
_ => Err(usage()),
}
}
/// One answer from the URnetwork API.
#[derive(Clone, Debug)]
struct ApiAnswer {
status: u16,
body: String,
}
/// The URnetwork API called with the root credential: real HTTPS, or the self-test's mock.
trait Api {
/// `POST <path>` with a JSON body.
fn post(&mut self, path: &str, body: &Value) -> Result<ApiAnswer, ToolError>;
/// `GET <path>?<query>`.
fn get(&mut self, path: &str, query: &[(&str, &str)]) -> Result<ApiAnswer, ToolError>;
}
/// The API origin: HTTPS, or explicit loopback HTTP for a local mock; no credentials, path, query
/// or fragment.
fn api_origin(base: &str) -> Result<reqwest::Url, ToolError> {
let invalid = || {
ToolError::Config(
"URNETWORK_API_URL must be an HTTPS origin, or explicit loopback HTTP for a mock"
.to_string(),
)
};
let url = reqwest::Url::parse(base).map_err(|_| invalid())?;
let local = matches!(
url.host_str(),
Some("localhost" | "127.0.0.1" | "[::1]" | "::1")
);
if url.host().is_none()
|| !url.username().is_empty()
|| url.password().is_some()
|| url.path() != "/"
|| url.query().is_some()
|| url.fragment().is_some()
|| (url.scheme() != "https" && !(url.scheme() == "http" && local))
{
return Err(invalid());
}
Ok(url)
}
/// The real API over HTTPS: no redirects, a timeout, bounded answers.
struct HttpApi {
origin: reqwest::Url,
root: String,
client: reqwest::blocking::Client,
}
impl HttpApi {
/// An API client with the root credential, which must be one token.
fn new(origin: reqwest::Url, root: String) -> Result<Self, ToolError> {
if root.is_empty() || root.chars().any(char::is_whitespace) {
return Err(ToolError::Config(
"set URNETWORK_ROOT_JWT to the backend root credential".to_string(),
));
}
let client = reqwest::blocking::Client::builder()
.timeout(Duration::from_secs(15))
.redirect(reqwest::redirect::Policy::none())
.build()
.map_err(|_| ToolError::Failure("could not create the HTTP client".to_string()))?;
Ok(Self {
origin,
root,
client,
})
}
/// The URL of a path on the origin.
fn url(&self, path: &str, query: &[(&str, &str)]) -> reqwest::Url {
let mut url = self.origin.clone();
url.set_path(path);
if !query.is_empty() {
let mut pairs = url.query_pairs_mut();
for (name, value) in query {
pairs.append_pair(name, value);
}
}
url
}
/// Reads a bounded answer.
fn answer(response: reqwest::blocking::Response) -> Result<ApiAnswer, ToolError> {
let status = response.status().as_u16();
let mut bytes = Vec::new();
response
.take(LIMIT + 1)
.read_to_end(&mut bytes)
.map_err(|_| {
ToolError::Failure("could not read the URnetwork API answer".to_string())
})?;
if bytes.len() as u64 > LIMIT {
return Err(ToolError::Failure(
"the URnetwork API answer is too large".to_string(),
));
}
let body = String::from_utf8(bytes)
.map_err(|_| ToolError::Failure("the URnetwork API answer is not UTF-8".to_string()))?;
Ok(ApiAnswer { status, body })
}
}
impl Api for HttpApi {
fn post(&mut self, path: &str, body: &Value) -> Result<ApiAnswer, ToolError> {
let response = self
.client
.post(self.url(path, &[]))
.bearer_auth(&self.root)
.json(body)
.send()
.map_err(|_| ToolError::Failure("could not reach the URnetwork API".to_string()))?;
Self::answer(response)
}
fn get(&mut self, path: &str, query: &[(&str, &str)]) -> Result<ApiAnswer, ToolError> {
let response = self
.client
.get(self.url(path, query))
.bearer_auth(&self.root)
.send()
.map_err(|_| ToolError::Failure("could not reach the URnetwork API".to_string()))?;
Self::answer(response)
}
}
/// One line of a server message, safe to print.
fn one_line(message: &str) -> String {
let line: String = message
.chars()
.map(|c| if c.is_control() { ' ' } else { c })
.take(300)
.collect();
line.trim().to_string()
}
/// The JSON object of a 2xx answer, or the error for a refused credential, a missing route or
/// another HTTP failure. `route` is the path that was called and `what` names the call in
/// messages.
fn answer_object(
answer: &ApiAnswer,
route: &str,
what: &str,
) -> Result<serde_json::Map<String, Value>, ToolError> {
match answer.status {
401 | 403 => {
return Err(ToolError::Config(
"the URnetwork API refused the root credential".to_string(),
));
}
// a server that predates the route (EMBED_CONTRACT.md, "Backend tools")
404 if route == ACL_PATH => {
return Err(ToolError::Failure(ACL_UNSUPPORTED_MESSAGE.to_string()));
}
404 if route == CAP_PATH || route == CAPS_PATH => {
return Err(ToolError::Failure(format!(
"{route} answered 404: the server predates the data-cap routes"
)));
}
404 if route == EMBED_PATH => {
return Err(ToolError::Failure(EMBED_UNSUPPORTED_MESSAGE.to_string()));
}
404 => {
return Err(ToolError::Failure(format!("{what}: {route} answered 404")));
}
200..=299 => {}
status => {
return Err(ToolError::Failure(format!(
"{what}: the URnetwork API answered HTTP {status}"
)));
}
}
match serde_json::from_str::<Value>(&answer.body) {
Ok(Value::Object(object)) => Ok(object),
_ => Err(ToolError::Failure(format!(
"{what}: the URnetwork API answered something other than a JSON object"
))),
}
}
/// The `error.message` of an answer object, when it carries an error.
fn error_message(object: &serde_json::Map<String, Value>) -> Option<String> {
let error = object.get("error").filter(|error| !error.is_null())?;
Some(
error
.get("message")
.and_then(Value::as_str)
.map(one_line)
.unwrap_or_default(),
)
}
/// Whether an answer object is the Embed-not-enabled refusal.
fn embed_not_enabled(object: &serde_json::Map<String, Value>) -> bool {
object
.get("error")
.and_then(|error| error.get("message"))
.and_then(Value::as_str)
== Some(EMBED_NOT_ENABLED_MESSAGE)
}
/// The `client_id` claim of a JWT, as a consistency check, not signature verification.
fn jwt_client_id(jwt: &str) -> Option<String> {
let parts: Vec<&str> = jwt.split('.').collect();
if parts.len() != 3 || parts.iter().any(|part| part.is_empty()) {
return None;
}
let claims: Value = serde_json::from_slice(
&URL_SAFE_LENIENT
.decode(parts[1].trim_end_matches('='))
.ok()?,
)
.ok()?;
claims["client_id"].as_str().map(str::to_string)
}
/// The auth-client request: a new client sends neither identity field; a reissue sends only its
/// stored `client_id`. Never `source_client_id`.
fn auth_client_request(client_id: Option<&str>) -> Value {
let mut body = json!({ "description": DESCRIPTION, "device_spec": DEVICE_SPEC });
if let Some(client_id) = client_id {
body["client_id"] = json!(client_id);
}
body
}
/// What an auth-client answer means.
enum AuthClientAnswer {
/// The client and its scoped JWT, checked.
Client {
client_id: String,
by_client_jwt: String,
},
/// The reissued client was removed or deactivated.
ClientDoesNotExist,
}
/// Checks an auth-client answer: the HTTP result, the API error (the client limit flags, a missing
/// client), both success fields, the JWT's `client_id` claim and, for a reissue, the mapped id.
fn read_auth_client_answer(
answer: &ApiAnswer,
expected: Option<&str>,
) -> Result<AuthClientAnswer, ToolError> {
let object = answer_object(answer, AUTH_CLIENT_PATH, "provision")?;
if let Some(error) = object.get("error").filter(|error| !error.is_null()) {
let flag = |name: &str| error.get(name).and_then(Value::as_bool).unwrap_or(false);
if flag("client_limit_exceeded") || flag("upgrade_required") {
return Err(ToolError::ClientLimit);
}
let message = error_message(&object).unwrap_or_default();
if message == CLIENT_DOES_NOT_EXIST {
return Ok(AuthClientAnswer::ClientDoesNotExist);
}
return Err(ToolError::Failure(format!(
"provision: the URnetwork API refused: {message}"
)));
}
let client_id = object
.get("client_id")
.and_then(Value::as_str)
.filter(|client_id| id_valid(client_id))
.ok_or_else(|| {
ToolError::Failure("provision: the answer has no valid client_id".to_string())
})?;
let by_client_jwt = object
.get("by_client_jwt")
.and_then(Value::as_str)
.filter(|jwt| !jwt.is_empty())
.ok_or_else(|| ToolError::Failure("provision: the answer has no scoped JWT".to_string()))?;
if jwt_client_id(by_client_jwt).as_deref() != Some(client_id)
|| expected.is_some_and(|expected| expected != client_id)
{
return Err(ToolError::Failure(
"provision: the scoped identity does not match".to_string(),
));
}
Ok(AuthClientAnswer::Client {
client_id: client_id.to_string(),
by_client_jwt: by_client_jwt.to_string(),
})
}
/// Loads the private map; a missing file is an empty map. Anything else that is not a private,
/// bounded file of the allocators' format, with valid keys and distinct valid ids, is a
/// configuration error.
fn load_map(file: &Path) -> Result<ClientMap, ToolError> {
let invalid = |reason: &str| ToolError::Config(format!("invalid client map: {reason}"));
let stat = match fs::symlink_metadata(file) {
Ok(stat) => stat,
Err(error) if error.kind() == io::ErrorKind::NotFound => {
return Ok(ClientMap {
version: 1,
clients: BTreeMap::new(),
pending_acl: Vec::new(),
});
}
Err(_) => return Err(invalid("unreadable")),
};
if !stat.is_file() || stat.len() > LIMIT {
return Err(invalid("not a regular file of bounded size"));
}
#[cfg(unix)]
if stat.permissions().mode() & 0o077 != 0 {
return Err(invalid("it must be private (0600)"));
}
let data = fs::read(file).map_err(|_| invalid("unreadable"))?;
let map: ClientMap = serde_json::from_slice(&data).map_err(|_| {
invalid("not the allocators' format (version, clients and pending_acl only)")
})?;
if map.version != 1 {
return Err(invalid("unknown version"));
}
let mut seen = BTreeSet::new();
for (key, client_id) in &map.clients {
if !key_valid(key) || !id_valid(client_id) || !seen.insert(client_id) {
return Err(invalid("an invalid or duplicate mapping"));
}
}
let mut pending = BTreeSet::new();
for key in &map.pending_acl {
if !map.clients.contains_key(key) || !pending.insert(key) {
return Err(invalid("pending_acl is not a list of mapped keys"));
}
}
Ok(map)
}
/// A unique suffix for temporary files.
fn unique_suffix() -> u128 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_nanos())
.unwrap_or(0)
}
/// Replaces a file atomically with owner-only permissions: a new temporary file in the same
/// directory, written, synced, then renamed over the old one.
fn write_private_atomically(file: &Path, data: &[u8]) -> io::Result<()> {
let temporary = file.with_extension(format!("{}.tmp", unique_suffix()));
let mut options = OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
options.mode(0o600);
let mut output = options.open(&temporary)?;
let result = (|| {
output.write_all(data)?;
output.sync_all()?;
drop(output);
fs::rename(&temporary, file)
})();
let _ = fs::remove_file(&temporary);
result
}
/// Saves the map.
fn save_map(file: &Path, map: &ClientMap) -> Result<(), ToolError> {
let data = serde_json::to_vec(map)
.map_err(|_| ToolError::Failure("could not encode the client map".to_string()))?;
write_private_atomically(file, &data)
.map_err(|_| ToolError::Failure("could not save the client map".to_string()))
}
/// The map's exclusive lock directory, removed on drop.
struct MapLock(PathBuf);
impl Drop for MapLock {
fn drop(&mut self) {
let _ = fs::remove_dir(&self.0);
}
}
/// Takes `<map>.lock`, held through the remote calls and the map update.
fn lock_map(file: &Path) -> Result<MapLock, ToolError> {
let lock = PathBuf::from(format!("{}.lock", file.display()));
match fs::create_dir(&lock) {
Ok(()) => {}
Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
return Err(ToolError::Failure(
"the client map is locked by another process; retry".to_string(),
));
}
Err(_) => {
return Err(ToolError::Config(
"could not lock the client map; its directory must exist".to_string(),
));
}
}
let guard = MapLock(lock);
#[cfg(unix)]
let _ = fs::set_permissions(&guard.0, fs::Permissions::from_mode(0o700));
Ok(guard)
}
/// The mapped client of a key.
fn mapped_client(map: &ClientMap, key: &str) -> Result<String, ToolError> {
map.clients
.get(key)
.cloned()
.ok_or_else(|| ToolError::Config(UNMAPPED_MESSAGE.to_string()))
}
/// Writes one JSON value as a line.
fn print_json(out: &mut dyn Write, value: &Value) -> Result<(), ToolError> {
writeln!(out, "{value}")?;
Ok(())
}
/// `provision <key> <client-jwt-file>`: reissues the key's client or provisions a new one; on
/// `Client does not exist.` it drops the mapping and provisions a new client. A new client goes into
/// `acl_group`, with a `pending_acl` record until the group is applied, before any client JWT is
/// written. Writes the client JWT to the file (owner-only, replaced atomically), never prints it,
/// and prints `{"client_id": ...}`. While Embed isn't enabled the record stays, with a line on
/// `err`, and a provision after the team enables Embed applies it.
fn provision(
key: &str,
client_jwt_file: &Path,
map_file: &Path,
acl_group: &str,
api: &mut dyn Api,
out: &mut dyn Write,
err: &mut dyn Write,
) -> Result<(), ToolError> {
let _lock = lock_map(map_file)?;
let mut map = load_map(map_file)?;
let mut mapped = map.clients.get(key).cloned();
let (client_id, by_client_jwt) = loop {
let answer = api.post(AUTH_CLIENT_PATH, &auth_client_request(mapped.as_deref()))?;
match read_auth_client_answer(&answer, mapped.as_deref())? {
AuthClientAnswer::Client {
client_id,
by_client_jwt,
} => break (client_id, by_client_jwt),
AuthClientAnswer::ClientDoesNotExist if mapped.is_some() => {
// deactivated after 30 days without connecting, or removed: provision a new client
map.clients.remove(key);
map.set_acl_pending(key, false);
save_map(map_file, &map)?;
mapped = None;
}
AuthClientAnswer::ClientDoesNotExist => {
return Err(ToolError::Failure(
"provision: the URnetwork API answered Client does not exist. for a new client"
.to_string(),
));
}
}
};
if mapped.is_none() {
if map
.clients
.values()
.any(|mapped_id| mapped_id == &client_id)
{
return Err(ToolError::Failure(
"provision: the new client is already mapped to another key".to_string(),
));
}
map.clients.insert(key.to_string(), client_id.clone());
// the mapping and the record that the client owes its group, in one save
map.set_acl_pending(key, acl_group == ACL_GROUP_ISOLATED);
save_map(map_file, &map)?;
}
let mut embed_enabled = true;
if map.acl_pending(key) {
// a new client is `default`: only an isolated default needs the request. A failure returns
// with the record kept, before any client JWT is written.
if acl_group == ACL_GROUP_ISOLATED {
match post_acl_group(api, &client_id, ACL_GROUP_ISOLATED) {
Ok(()) => {}
// while Embed isn't enabled the record stays and the client works
Err(ToolError::EmbedNotEnabled) => embed_enabled = false,
Err(error) => return Err(error),
}
}
if embed_enabled {
map.set_acl_pending(key, false);
save_map(map_file, &map)?;
}
}
write_private_atomically(client_jwt_file, format!("{by_client_jwt}\n").as_bytes())
.map_err(|_| ToolError::Failure("could not write the client JWT file".to_string()))?;
print_json(out, &json!({ "client_id": client_id }))?;
if !embed_enabled {
writeln!(err, "{EMBED_PENDING_LINE}")?;
}
Ok(())
}
/// Sets the client's ACL group; the answer must name the client and the group.
fn post_acl_group(api: &mut dyn Api, client_id: &str, group: &str) -> Result<(), ToolError> {
let answer = api.post(
ACL_PATH,
&json!({ "client_id": client_id, "acl_group": group }),
)?;
let object = answer_object(&answer, ACL_PATH, "acl")?;
if embed_not_enabled(&object) {
return Err(ToolError::EmbedNotEnabled);
}
if let Some(message) = error_message(&object) {
return Err(ToolError::Failure(format!(
"acl: the URnetwork API refused: {message}"
)));
}
if object.get("client_id").and_then(Value::as_str) != Some(client_id)
|| object.get("acl_group").and_then(Value::as_str) != Some(group)
{
return Err(ToolError::Failure(
"acl: the URnetwork API answered another client or ACL group".to_string(),
));
}
Ok(())
}
/// `acl <key> default|isolated`: sets the ACL group of the key's client and prints `{"client_id":
/// ..., "acl_group": ...}`. An explicit group settles a pending default group, so the record is
/// dropped.
fn acl(
key: &str,
group: &str,
map_file: &Path,
api: &mut dyn Api,
out: &mut dyn Write,
) -> Result<(), ToolError> {
let _lock = lock_map(map_file)?;
let mut map = load_map(map_file)?;
let client_id = mapped_client(&map, key)?;
post_acl_group(api, &client_id, group)?;
if map.acl_pending(key) {
map.set_acl_pending(key, false);
save_map(map_file, &map)?;
}
// the contract's key order, which a serialized map would sort
writeln!(
out,
"{{\"client_id\":{},\"acl_group\":{}}}",
json!(client_id),
json!(group)
)?;
Ok(())
}
/// The cap object of an answer, refused when it carries an error.
fn cap_object(answer: &ApiAnswer, route: &str, what: &str) -> Result<Value, ToolError> {
let object = answer_object(answer, route, what)?;
if embed_not_enabled(&object) {
return Err(ToolError::EmbedNotEnabled);
}
if let Some(message) = error_message(&object) {
return Err(ToolError::Failure(format!(
"{what}: the URnetwork API refused: {message}"
)));
}
Ok(Value::Object(object))
}
/// The merge body of `POST /network/client-data-cap`: only the given fields. An omitted option is
/// absent from the JSON, `null` is JSON `null`, byte counts are integers, and `reset_total` appears
/// only when given.
fn cap_request(
client_id: &str,
monthly: Option<CapValue>,
total: Option<CapValue>,
reset_total: bool,
) -> Value {
let mut body = json!({ "client_id": client_id });
if let Some(monthly) = monthly {
body["monthly_byte_limit"] = monthly.to_json();
}
if let Some(total) = total {
body["total_byte_limit"] = total.to_json();
}
if reset_total {
body["reset_total"] = json!(true);
}
body
}
/// `cap <key> ...`: posts only the given fields and prints the cap object.
fn cap(
key: &str,
monthly: Option<CapValue>,
total: Option<CapValue>,
reset_total: bool,
map_file: &Path,
api: &mut dyn Api,
out: &mut dyn Write,
) -> Result<(), ToolError> {
let client_id = mapped_client(&load_map(map_file)?, key)?;
let answer = api.post(
CAP_PATH,
&cap_request(&client_id, monthly, total, reset_total),
)?;
print_json(out, &cap_object(&answer, CAP_PATH, "cap")?)
}
/// `usage <key>`: prints the key's cap object, read with the root credential.
fn usage(
key: &str,
map_file: &Path,
api: &mut dyn Api,
out: &mut dyn Write,
) -> Result<(), ToolError> {
let client_id = mapped_client(&load_map(map_file)?, key)?;
let answer = api.get(CAP_PATH, &[("client_id", &client_id)])?;
print_json(out, &cap_object(&answer, CAP_PATH, "usage")?)
}
/// `usage-all`: pages through `GET /network/client-data-caps` and prints one cap object per line,
/// stopping at a `null` cursor or a repeated one.
fn usage_all(api: &mut dyn Api, out: &mut dyn Write) -> Result<(), ToolError> {
let mut cursor: Option<String> = None;
let mut seen_cursors = BTreeSet::new();
loop {
let mut query = vec![("limit", USAGE_ALL_PAGE_SIZE)];
if let Some(cursor) = &cursor {
query.push(("cursor", cursor.as_str()));
}
let answer = api.get(CAPS_PATH, &query)?;
let page = cap_object(&answer, CAPS_PATH, "usage-all")?;
let clients = page
.get("clients")
.and_then(Value::as_array)
.ok_or_else(|| {
ToolError::Failure("usage-all: the page has no clients list".to_string())
})?;
for client in clients {
print_json(out, client)?;
}
match page.get("next_cursor").and_then(Value::as_str) {
Some(next) if !next.is_empty() && seen_cursors.insert(next.to_string()) => {
cursor = Some(next.to_string());
}
// a null cursor ends the list; a repeated one would loop forever
_ => return Ok(()),
}
}
}
/// `remove <key>`: removes the key's client, then the mapping (also when the answer is `Client does
/// not exist.`), and prints `{"removed": ...}`.
fn remove(
key: &str,
map_file: &Path,
api: &mut dyn Api,
out: &mut dyn Write,
) -> Result<(), ToolError> {
let _lock = lock_map(map_file)?;
let mut map = load_map(map_file)?;
let client_id = mapped_client(&map, key)?;
let answer = api.post(REMOVE_PATH, &json!({ "client_id": client_id }))?;
let object = answer_object(&answer, REMOVE_PATH, "remove")?;
// `Client does not exist.` means the client is already gone: drop the mapping too
if let Some(message) = error_message(&object).filter(|message| message != CLIENT_DOES_NOT_EXIST)
{
return Err(ToolError::Failure(format!(
"remove: the URnetwork API refused: {message}"
)));
}
map.clients.remove(key);
map.set_acl_pending(key, false);
save_map(map_file, &map)?;
print_json(out, &json!({ "removed": client_id }))
}
/// `status`: prints the network's Embed state from `GET /network/embed` as one line, `embed
/// enabled: yes | client limit: 5000 | active clients: 1234`. A refusal, such as for a client JWT,
/// is a configuration problem.
fn embed_status(api: &mut dyn Api, out: &mut dyn Write) -> Result<(), ToolError> {
let answer = api.get(EMBED_PATH, &[])?;
let object = answer_object(&answer, EMBED_PATH, "status")?;
if let Some(message) = error_message(&object) {
return Err(ToolError::Config(format!(
"status: the URnetwork API refused: {message}"
)));
}
let (Some(enabled), Some(client_limit), Some(active_client_count)) = (
object.get("enabled").and_then(Value::as_bool),
object.get("client_limit").and_then(Value::as_u64),
object.get("active_client_count").and_then(Value::as_u64),
) else {
return Err(ToolError::Failure(
"status: the URnetwork API answered something that is not an Embed state".to_string(),
));
};
let enabled = if enabled { "yes" } else { "no" };
writeln!(
out,
"embed enabled: {enabled} | client limit: {client_limit} | active clients: {active_client_count}"
)?;
Ok(())
}
/// Runs a parsed command other than the self-test; `acl_group` is the ACL group of each new client.
fn execute(
command: &Command,
map_file: &Path,
acl_group: &str,
api: &mut dyn Api,
out: &mut dyn Write,
err: &mut dyn Write,
) -> Result<(), ToolError> {
if !map_file.is_absolute() {
return Err(ToolError::Config(
"set URNETWORK_CLIENT_MAP to an absolute file path".to_string(),
));
}
match command {
Command::Provision {
key,
client_jwt_file,
} => provision(key, client_jwt_file, map_file, acl_group, api, out, err),
Command::Cap {
key,
monthly,
total,
reset_total,
} => cap(key, *monthly, *total, *reset_total, map_file, api, out),
Command::Usage { key } => usage(key, map_file, api, out),
Command::UsageAll => usage_all(api, out),
Command::Remove { key } => remove(key, map_file, api, out),
Command::Acl { key, group } => acl(key, group, map_file, api, out),
Command::Status => embed_status(api, out),
Command::SelfTest => Err(ToolError::Config(USAGE.to_string())),
}
}
/// A required setting.
fn required_setting(name: &str) -> Result<String, ToolError> {
env::var(name)
.ok()
.filter(|value| !value.trim().is_empty())
.ok_or_else(|| ToolError::Config(format!("set {name}")))
}
/// Parses the arguments, reads the settings and runs the command. Returns the exit code; errors are
/// printed as one line on `err`.
fn run(args: &[String], out: &mut dyn Write, err: &mut dyn Write) -> i32 {
let result = parse_command(args).and_then(|command| {
if command == Command::SelfTest {
return self_test::run(out);
}
let map_file = PathBuf::from(required_setting("URNETWORK_CLIENT_MAP")?);
let origin = api_origin(
&env::var("URNETWORK_API_URL").unwrap_or_else(|_| "https://api.bringyour.com".into()),
)?;
let acl_group = default_acl_group(env::var("URNETWORK_DEFAULT_ACL_GROUP").ok().as_deref())?;
let mut api = HttpApi::new(origin, required_setting("URNETWORK_ROOT_JWT")?)?;
execute(&command, &map_file, acl_group, &mut api, out, err)
});
match result {
Ok(()) => EXIT_OK,
Err(error) => {
let _ = writeln!(err, "{}", error.message());
error.exit_code()
}
}
}
fn main() {
let args: Vec<String> = env::args().skip(1).collect();
let code = run(&args, &mut io::stdout().lock(), &mut io::stderr().lock());
std::process::exit(code);
}
/// The credential-free self-test (EMBED_CONTRACT.md, "Backend tools"): every command against a mock
/// API, in a private temporary directory, without credentials or a network.
mod self_test {
use std::collections::VecDeque;
use super::*;
const CLIENT_A: &str = "11111111-1111-1111-1111-111111111111";
const CLIENT_B: &str = "22222222-2222-2222-2222-222222222222";
const KEY: &str = "user:alice:33333333-3333-3333-3333-333333333333";
/// One recorded call.
#[derive(Clone, Debug)]
struct Call {
method: &'static str,
path: String,
body: Option<Value>,
query: Vec<(String, String)>,
}
/// Answers calls in order and records them.
struct MockApi {
answers: VecDeque<ApiAnswer>,
calls: Vec<Call>,
}
impl MockApi {
fn new(answers: &[(u16, Value)]) -> Self {
Self {
answers: answers
.iter()
.map(|(status, body)| ApiAnswer {
status: *status,
body: body.to_string(),
})
.collect(),
calls: Vec::new(),
}
}
fn next(&mut self) -> Result<ApiAnswer, ToolError> {
self.answers
.pop_front()
.ok_or_else(|| ToolError::Failure("mock: no more answers".to_string()))
}
}
impl Api for MockApi {
fn post(&mut self, path: &str, body: &Value) -> Result<ApiAnswer, ToolError> {
self.calls.push(Call {
method: "POST",
path: path.to_string(),
body: Some(body.clone()),
query: Vec::new(),
});
self.next()
}
fn get(&mut self, path: &str, query: &[(&str, &str)]) -> Result<ApiAnswer, ToolError> {
self.calls.push(Call {
method: "GET",
path: path.to_string(),
body: None,
query: query
.iter()
.map(|(name, value)| (name.to_string(), value.to_string()))
.collect(),
});
self.next()
}
}
/// A synthetic, unsigned JWT for a client.
fn jwt(client_id: &str) -> String {
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
format!(
"e30.{}.test",
URL_SAFE_NO_PAD.encode(json!({ "client_id": client_id }).to_string())
)
}
/// An auth-client success answer.
fn auth_ok(client_id: &str) -> (u16, Value) {
(
200,
json!({ "client_id": client_id, "by_client_jwt": jwt(client_id) }),
)
}
/// An API error answer.
fn api_error(message: &str) -> (u16, Value) {
(
200,
json!({ "error": { "client_limit_exceeded": false, "message": message } }),
)
}
/// A cap object answer.
fn cap_answer(client_id: &str) -> (u16, Value) {
(
200,
json!({ "client_id": client_id, "monthly_byte_limit": 10000000000u64, "monthly_used_byte_count": 0, "total_byte_limit": null, "total_used_byte_count": 0, "capped": false, "capped_reason": "" }),
)
}
/// Runs a command against the mock with new clients in `default`, which sends no ACL request;
/// returns the exit code, stdout and stderr.
fn invoke(args: &[&str], map_file: &Path, api: &mut MockApi) -> (i32, String, String) {
invoke_with(args, map_file, ACL_GROUP_DEFAULT, api)
}
/// Runs a command against the mock with new clients in `acl_group`.
fn invoke_with(
args: &[&str],
map_file: &Path,
acl_group: &str,
api: &mut MockApi,
) -> (i32, String, String) {
let args: Vec<String> = args.iter().map(|arg| arg.to_string()).collect();
let mut out = Vec::new();
let mut err = Vec::new();
let result = parse_command(&args)
.and_then(|command| execute(&command, map_file, acl_group, api, &mut out, &mut err));
let mut err = String::from_utf8_lossy(&err).into_owned();
let code = match result {
Ok(()) => EXIT_OK,
Err(error) => {
err.push_str(&format!("{}\n", error.message()));
error.exit_code()
}
};
(code, String::from_utf8_lossy(&out).into_owned(), err)
}
/// Fails with a message unless the condition holds.
fn ensure(condition: bool, message: &str) -> Result<(), ToolError> {
if condition {
Ok(())
} else {
Err(ToolError::Failure(format!("self-test: {message}")))
}
}
/// The POSIX mode of a file.
#[cfg(unix)]
fn mode(path: &Path) -> u32 {
fs::metadata(path)
.map(|metadata| metadata.permissions().mode() & 0o777)
.unwrap_or(0)
}
/// Runs every check in a private temporary directory, then prints the passed line.
pub(super) fn run(out: &mut dyn Write) -> Result<(), ToolError> {
let dir = env::temp_dir().join(format!(
"ur-embed-server-{}-{}",
std::process::id(),
unique_suffix()
));
fs::create_dir(&dir)?;
#[cfg(unix)]
fs::set_permissions(&dir, fs::Permissions::from_mode(0o700))?;
let result = checks(&dir)
.and_then(|()| acl_checks(&dir))
.and_then(|()| embed_not_enabled_checks(&dir))
.and_then(|()| embed_status_checks(&dir))
.and_then(|()| failure_text_checks(&dir));
let _ = fs::remove_dir_all(&dir);
result?;
writeln!(out, "embed backend tool self-test passed")?;
Ok(())
}
fn checks(dir: &Path) -> Result<(), ToolError> {
let map_file = dir.join("clients.json");
let jwt_file = dir.join("alice.jwt");
let jwt_path = jwt_file.to_str().unwrap_or_default().to_string();
// new versus reissue: a new client sends neither identity field, a reissue its stored id
let mut api = MockApi::new(&[auth_ok(CLIENT_A), auth_ok(CLIENT_A)]);
let (code, stdout, stderr) = invoke(&["provision", KEY, &jwt_path], &map_file, &mut api);
ensure(code == EXIT_OK, &format!("provision failed: {stderr}"))?;
ensure(
stdout == format!("{{\"client_id\":\"{CLIENT_A}\"}}\n"),
"provision stdout",
)?;
let first = api.calls[0].body.clone().unwrap_or_default();
ensure(
first == json!({ "description": DESCRIPTION, "device_spec": DEVICE_SPEC }),
"a new client's request carries an identity field",
)?;
ensure(
api.calls[0].method == "POST" && api.calls[0].path == "/network/auth-client",
"provision posts to /network/auth-client",
)?;
// the token reaches the private file, never stdout or stderr
let saved = fs::read_to_string(&jwt_file)?;
ensure(saved.trim() == jwt(CLIENT_A), "the client JWT file content")?;
ensure(
!stdout.contains(&jwt(CLIENT_A)) && !stderr.contains("e30."),
"the token was printed",
)?;
#[cfg(unix)]
ensure(
mode(&jwt_file) == 0o600,
"the client JWT file is not private",
)?;
#[cfg(unix)]
ensure(mode(&map_file) == 0o600, "the map is not private")?;
let (code, _, _) = invoke(&["provision", KEY, &jwt_path], &map_file, &mut api);
ensure(code == EXIT_OK, "reissue failed")?;
let second = api.calls[1].body.clone().unwrap_or_default();
ensure(
second["client_id"] == CLIENT_A,
"a reissue does not send its stored client_id",
)?;
ensure(
api.calls.iter().all(|call| {
call.body
.as_ref()
.is_none_or(|body| body.get("source_client_id").is_none())
}),
"a request carries source_client_id",
)?;
ensure(
load_map(&map_file)?.clients.get(KEY).map(String::as_str) == Some(CLIENT_A),
"the mapping",
)?;
ensure(
!PathBuf::from(format!("{}.lock", map_file.display())).exists(),
"the lock was left behind",
)?;
// Client does not exist.: drop the mapping and provision a new client
let mut api = MockApi::new(&[api_error(CLIENT_DOES_NOT_EXIST), auth_ok(CLIENT_B)]);
let (code, stdout, stderr) = invoke(&["provision", KEY, &jwt_path], &map_file, &mut api);
ensure(code == EXIT_OK, &format!("re-provision failed: {stderr}"))?;
ensure(
api.calls[0]
.body
.as_ref()
.is_some_and(|body| body["client_id"] == CLIENT_A),
"the reissue",
)?;
ensure(
api.calls[1]
.body
.as_ref()
.is_some_and(|body| body.get("client_id").is_none()),
"the new provision sends client_id",
)?;
ensure(stdout.contains(CLIENT_B), "the new client is not printed")?;
ensure(
load_map(&map_file)?.clients.get(KEY).map(String::as_str) == Some(CLIENT_B),
"the new mapping",
)?;
// response and claim checks: nothing changes the map
let mismatched = (
200,
json!({ "client_id": CLIENT_A, "by_client_jwt": jwt(CLIENT_B) }),
);
let missing_jwt = (200, json!({ "client_id": CLIENT_A }));
let reissued_other = auth_ok(CLIENT_A);
for (answer, what) in [
(mismatched, "a JWT for another client"),
(missing_jwt, "a missing JWT"),
(reissued_other, "a reissue answering another client"),
(api_error("Something else."), "another API error"),
((500, json!({})), "an HTTP 500"),
] {
let mut api = MockApi::new(&[answer]);
let (code, _, _) = invoke(&["provision", KEY, &jwt_path], &map_file, &mut api);
ensure(
code == EXIT_FAILURE,
&format!("{what} did not fail with exit 1"),
)?;
ensure(
load_map(&map_file)?.clients.get(KEY).map(String::as_str) == Some(CLIENT_B),
&format!("{what} changed the map"),
)?;
}
// a new client already mapped to another key
let mut api = MockApi::new(&[auth_ok(CLIENT_B)]);
let (code, _, _) = invoke(
&[
"provision",
"user:bob",
&dir.join("bob.jwt").to_string_lossy(),
],
&map_file,
&mut api,
);
ensure(
code == EXIT_FAILURE,
"a client mapped to another key was accepted",
)?;
// the client limit, both flags, and a refused root credential exit 78
for error in [
json!({ "error": { "client_limit_exceeded": true, "message": "Client limit exceeded." } }),
json!({ "error": { "client_limit_exceeded": false, "upgrade_required": true, "message": "Upgrade required." } }),
] {
let mut api = MockApi::new(&[(200, error)]);
let (code, stdout, stderr) = invoke(
&[
"provision",
"user:carol",
&dir.join("carol.jwt").to_string_lossy(),
],
&map_file,
&mut api,
);
ensure(
code == EXIT_CONFIG && stdout.is_empty(),
"the client limit did not exit 78",
)?;
ensure(
stderr == format!("{CLIENT_LIMIT_MESSAGE}\n"),
"the client limit message",
)?;
}
let mut api = MockApi::new(&[(401, json!({}))]);
let (code, _, _) = invoke(&["usage", KEY], &map_file, &mut api);
ensure(
code == EXIT_CONFIG,
"a refused root credential did not exit 78",
)?;
// key and argument rejection
for args in [
vec!["provision", "alice", "x.jwt"],
vec!["provision", "user:", "x.jwt"],
vec!["provision", "user:../a", "x.jwt"],
vec!["provision", "user:a b", "x.jwt"],
vec!["provision", CLIENT_A, "x.jwt"],
vec!["provision", KEY],
vec!["provision", KEY, ""],
vec!["cap", KEY],
vec!["cap", KEY, "--monthly"],
vec!["cap", KEY, "--monthly", "5GB"],
vec!["cap", KEY, "--monthly", "-1"],
vec!["cap", KEY, "--monthly", "+5"],
vec!["cap", KEY, "--monthly", "1e9"],
vec!["cap", KEY, "--monthly", "9223372036854775808"],
vec!["cap", KEY, "--monthly", "1", "--monthly", "2"],
vec!["cap", KEY, "--reset-total", "--reset-total"],
vec!["cap", KEY, "--weekly", "1"],
vec!["usage-all", "extra"],
vec!["status", "extra"],
vec!["remove"],
vec!["--unknown"],
vec![],
] {
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&args, &map_file, &mut api);
ensure(
code == EXIT_CONFIG && api.calls.is_empty(),
&format!("arguments {args:?} were accepted"),
)?;
}
let long_key = format!("user:{}", "a".repeat(124));
ensure(
!key_valid(&long_key) && key_valid(&long_key[..128]),
"the key length limit",
)?;
ensure(
parse_cap_value("9223372036854775807") == Ok(CapValue::Bytes(9223372036854775807)),
"the largest cap",
)?;
ensure(parse_cap_value("0") == Ok(CapValue::Bytes(0)), "a zero cap")?;
// merge request bodies: only the given fields
for (args, want) in [
(
vec!["--monthly", "10000000000"],
json!({ "client_id": CLIENT_B, "monthly_byte_limit": 10000000000u64 }),
),
(
vec!["--monthly", "null"],
json!({ "client_id": CLIENT_B, "monthly_byte_limit": null }),
),
(
vec!["--total", "0", "--reset-total"],
json!({ "client_id": CLIENT_B, "total_byte_limit": 0, "reset_total": true }),
),
(
vec!["--reset-total"],
json!({ "client_id": CLIENT_B, "reset_total": true }),
),
] {
let mut api = MockApi::new(&[cap_answer(CLIENT_B)]);
let mut command = vec!["cap", KEY];
command.extend(args.iter().copied());
let (code, stdout, _) = invoke(&command, &map_file, &mut api);
ensure(code == EXIT_OK, &format!("cap {args:?} failed"))?;
let body = api.calls[0].body.clone().unwrap_or_default();
ensure(body == want, &format!("cap {args:?} posted {body}"))?;
ensure(
api.calls[0].path == "/network/client-data-cap",
"the cap path",
)?;
if let Some(limit) = body
.get("monthly_byte_limit")
.filter(|limit| !limit.is_null())
{
ensure(limit.is_u64(), "a byte count is not a JSON integer")?;
}
// the cap object is printed as one line
ensure(
stdout.lines().count() == 1
&& stdout.contains("\"monthly_byte_limit\":10000000000"),
"the cap object output",
)?;
}
// a cap error or a server without the routes fails with exit 1
for answer in [api_error("Client does not exist."), (404, json!({}))] {
let mut api = MockApi::new(&[answer]);
let (code, stdout, _) = invoke(&["cap", KEY, "--monthly", "1"], &map_file, &mut api);
ensure(
code == EXIT_FAILURE && stdout.is_empty(),
"a failed cap did not exit 1",
)?;
}
// usage reads the key's client with the root credential
let mut api = MockApi::new(&[cap_answer(CLIENT_B)]);
let (code, stdout, _) = invoke(&["usage", KEY], &map_file, &mut api);
ensure(code == EXIT_OK && stdout.contains(CLIENT_B), "usage failed")?;
ensure(
api.calls[0].method == "GET"
&& api.calls[0].path == "/network/client-data-cap"
&& api.calls[0].query == [("client_id".to_string(), CLIENT_B.to_string())],
"usage reads GET /network/client-data-cap?client_id=",
)?;
// an unmapped key is a configuration error
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&["usage", "user:nobody"], &map_file, &mut api);
ensure(
code == EXIT_CONFIG && api.calls.is_empty(),
"an unmapped key was read",
)?;
// usage-all pages, and stops at a repeated cursor and at a null cursor
let mut api = MockApi::new(&[
(
200,
json!({ "clients": [cap_answer(CLIENT_A).1, cap_answer(CLIENT_B).1], "next_cursor": "c1" }),
),
(
200,
json!({ "clients": [cap_answer(CLIENT_A).1], "next_cursor": "c2" }),
),
(200, json!({ "clients": [], "next_cursor": "c2" })),
]);
let (code, stdout, _) = invoke(&["usage-all"], &map_file, &mut api);
ensure(
code == EXIT_OK && stdout.lines().count() == 3,
"usage-all lines",
)?;
ensure(
api.calls.len() == 3,
"usage-all did not stop at a repeated cursor",
)?;
ensure(
api.calls[0].query == [("limit".to_string(), "1000".to_string())],
"the first page query",
)?;
ensure(
api.calls[2]
.query
.contains(&("cursor".to_string(), "c2".to_string())),
"the cursor query",
)?;
let mut api = MockApi::new(&[(
200,
json!({ "clients": [cap_answer(CLIENT_A).1], "next_cursor": null }),
)]);
let (code, stdout, _) = invoke(&["usage-all"], &map_file, &mut api);
ensure(
code == EXIT_OK && stdout.lines().count() == 1 && api.calls.len() == 1,
"usage-all with a null cursor",
)?;
// remove drops the mapping for both answers, and keeps it on another error
for answer in [(200, json!({})), api_error(CLIENT_DOES_NOT_EXIST)] {
let mut map = load_map(&map_file)?;
map.clients.insert(KEY.to_string(), CLIENT_B.to_string());
save_map(&map_file, &map)?;
let mut api = MockApi::new(&[answer]);
let (code, stdout, _) = invoke(&["remove", KEY], &map_file, &mut api);
ensure(code == EXIT_OK, "remove failed")?;
ensure(
stdout == format!("{{\"removed\":\"{CLIENT_B}\"}}\n"),
"remove stdout",
)?;
ensure(
api.calls[0].body == Some(json!({ "client_id": CLIENT_B })),
"the remove request",
)?;
ensure(
!load_map(&map_file)?.clients.contains_key(KEY),
"remove kept the mapping",
)?;
}
let mut map = load_map(&map_file)?;
map.clients.insert(KEY.to_string(), CLIENT_B.to_string());
save_map(&map_file, &map)?;
let mut api = MockApi::new(&[api_error("Something else.")]);
let (code, _, _) = invoke(&["remove", KEY], &map_file, &mut api);
ensure(
code == EXIT_FAILURE && load_map(&map_file)?.clients.contains_key(KEY),
"a failed remove dropped the mapping",
)?;
// a map with unknown fields, such as the token server's, is refused
let token_server_map = dir.join("token-server-clients.json");
write_private_atomically(
&token_server_map,
json!({ "version": 1, "clients": {}, "pending_caps": [] })
.to_string()
.as_bytes(),
)?;
let mut api = MockApi::new(&[auth_ok(CLIENT_A)]);
let (code, _, _) = invoke(&["provision", KEY, &jwt_path], &token_server_map, &mut api);
ensure(
code == EXIT_CONFIG && api.calls.is_empty(),
"a map with pending_caps was accepted",
)?;
// a group-readable map is refused
#[cfg(unix)]
{
fs::set_permissions(&map_file, fs::Permissions::from_mode(0o644))?;
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&["usage", KEY], &map_file, &mut api);
ensure(code == EXIT_CONFIG, "a group-readable map was accepted")?;
fs::set_permissions(&map_file, fs::Permissions::from_mode(0o600))?;
}
// a relative map path is refused
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&["usage-all"], Path::new("clients.json"), &mut api);
ensure(code == EXIT_CONFIG, "a relative map path was accepted")?;
// the API origin rules
ensure(
api_origin("https://api.bringyour.com").is_ok(),
"the default origin",
)?;
ensure(
api_origin("http://127.0.0.1:8080").is_ok(),
"a loopback mock origin",
)?;
for origin in [
"http://example.com",
"https://example.com/path",
"https://user@example.com",
] {
ensure(
api_origin(origin).is_err(),
&format!("origin {origin} was accepted"),
)?;
}
Ok(())
}
/// An ACL group answer.
fn acl_answer(client_id: &str, group: &str) -> (u16, Value) {
(200, json!({ "client_id": client_id, "acl_group": group }))
}
/// The keys a map file records in `pending_acl`.
fn pending(map_file: &Path) -> Result<Vec<String>, ToolError> {
Ok(load_map(map_file)?.pending_acl)
}
/// The default ACL group: applied to a new client only, with `pending_acl` set before and
/// cleared after, kept and retried after a failure, kept on a server without ACL groups, and
/// settled by `acl`; the `acl` command.
fn acl_checks(dir: &Path) -> Result<(), ToolError> {
let map_file = dir.join("acl.json");
let jwt_file = dir.join("ivan.jwt");
let jwt_path = jwt_file.to_string_lossy().to_string();
// the setting: unset or empty means isolated, other values are a configuration error
ensure(
default_acl_group(None) == Ok(ACL_GROUP_ISOLATED)
&& default_acl_group(Some("")) == Ok(ACL_GROUP_ISOLATED)
&& default_acl_group(Some("default")) == Ok(ACL_GROUP_DEFAULT)
&& default_acl_group(Some("private")).is_err_and(|error| {
error.exit_code() == EXIT_CONFIG
&& error.message()
== "URNETWORK_DEFAULT_ACL_GROUP must be default or isolated"
}),
"the default ACL group setting",
)?;
// isolated: the new client, then one ACL request, then no record
let mut api = MockApi::new(&[auth_ok(CLIENT_A), acl_answer(CLIENT_A, ACL_GROUP_ISOLATED)]);
let (code, _, stderr) = invoke_with(
&["provision", "user:ivan", &jwt_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK,
&format!("isolated provision failed: {stderr}"),
)?;
ensure(
api.calls.len() == 2
&& api.calls[1].path == ACL_PATH
&& api.calls[1].body
== Some(json!({ "client_id": CLIENT_A, "acl_group": ACL_GROUP_ISOLATED })),
"a new client is not put in isolated",
)?;
ensure(
pending(&map_file)?.is_empty()
&& !fs::read_to_string(&map_file)?.contains("pending_acl")
&& fs::read_to_string(&jwt_file)?.trim() == jwt(CLIENT_A),
"an applied group leaves its record or no client JWT",
)?;
let mut api = MockApi::new(&[auth_ok(CLIENT_A)]);
let (code, _, _) = invoke_with(
&["provision", "user:ivan", &jwt_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK && api.calls.len() == 1,
"a reissue sends an ACL request",
)?;
// a failed request keeps the record and writes no client JWT; the next issue retries
let judy_jwt = dir.join("judy.jwt");
let judy_path = judy_jwt.to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(CLIENT_B), (500, json!({}))]);
let (code, _, _) = invoke_with(
&["provision", "user:judy", &judy_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_FAILURE
&& !judy_jwt.exists()
&& pending(&map_file)? == ["user:judy"]
&& load_map(&map_file)?
.clients
.get("user:judy")
.map(String::as_str)
== Some(CLIENT_B),
"a failed ACL request does not keep the record",
)?;
let mut api = MockApi::new(&[auth_ok(CLIENT_B), acl_answer(CLIENT_B, ACL_GROUP_ISOLATED)]);
let (code, _, _) = invoke_with(
&["provision", "user:judy", &judy_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK
&& api.calls.len() == 2
&& api.calls[1].path == ACL_PATH
&& pending(&map_file)?.is_empty()
&& judy_jwt.exists(),
"a pending group is not applied on the next issue",
)?;
// a server without ACL groups: exit 1 with its line and the record kept; a default of
// default then provisions without a request
let older_map = dir.join("older.json");
let kim = "55555555-5555-5555-5555-555555555555";
let kim_jwt = dir.join("kim.jwt");
let kim_path = kim_jwt.to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(kim), (404, json!({}))]);
let (code, _, stderr) = invoke_with(
&["provision", "user:kim", &kim_path],
&older_map,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_FAILURE
&& stderr == format!("{ACL_UNSUPPORTED_MESSAGE}\n")
&& !kim_jwt.exists()
&& pending(&older_map)? == ["user:kim"],
&format!("a server without ACL groups answers {code}: {stderr}"),
)?;
let mut api = MockApi::new(&[auth_ok(kim)]);
let (code, _, _) = invoke(&["provision", "user:kim", &kim_path], &older_map, &mut api);
ensure(
code == EXIT_OK
&& api.calls.len() == 1
&& pending(&older_map)?.is_empty()
&& kim_jwt.exists(),
"a default of default does not settle the record without a request",
)?;
// the acl command: the request, the printed answer, and its refusals
let mut api = MockApi::new(&[acl_answer(CLIENT_A, ACL_GROUP_DEFAULT)]);
let (code, stdout, _) = invoke(&["acl", "user:ivan", "default"], &map_file, &mut api);
ensure(
code == EXIT_OK
&& stdout
== format!("{{\"client_id\":\"{CLIENT_A}\",\"acl_group\":\"default\"}}\n")
&& api.calls[0].body
== Some(json!({ "client_id": CLIENT_A, "acl_group": "default" })),
&format!("acl printed {stdout}"),
)?;
for args in [
vec!["acl"],
vec!["acl", "user:ivan"],
vec!["acl", "user:ivan", "public"],
vec!["acl", "user:ivan", "Default"],
vec!["acl", "user:ivan", "default", "extra"],
vec!["acl", "alice", "default"],
] {
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&args, &map_file, &mut api);
ensure(
code == EXIT_CONFIG && api.calls.is_empty(),
&format!("arguments {args:?} were accepted"),
)?;
}
for (answer, what) in [
(
acl_answer(CLIENT_A, ACL_GROUP_DEFAULT),
"an answer for another group",
),
(api_error(CLIENT_DOES_NOT_EXIST), "a refusal"),
] {
let mut api = MockApi::new(&[answer]);
let (code, _, _) = invoke(&["acl", "user:ivan", "isolated"], &map_file, &mut api);
ensure(code == EXIT_FAILURE, &format!("{what} was accepted"))?;
}
let mut api = MockApi::new(&[(404, json!({}))]);
let (code, _, stderr) = invoke(&["acl", "user:ivan", "isolated"], &map_file, &mut api);
ensure(
code == EXIT_FAILURE && stderr == format!("{ACL_UNSUPPORTED_MESSAGE}\n"),
&format!("acl on a server without ACL groups: {stderr}"),
)?;
// an explicit group settles a pending record, so a later issue keeps it
let mia = "66666666-6666-6666-6666-666666666666";
let mia_path = dir.join("mia.jwt").to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(mia), (500, json!({}))]);
invoke_with(
&["provision", "user:mia", &mia_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
pending(&map_file)? == ["user:mia"],
"the failed group is not recorded",
)?;
let mut api = MockApi::new(&[acl_answer(mia, ACL_GROUP_DEFAULT)]);
let (code, _, _) = invoke(&["acl", "user:mia", "default"], &map_file, &mut api);
ensure(
code == EXIT_OK && pending(&map_file)?.is_empty(),
"acl does not settle a pending record",
)?;
let mut api = MockApi::new(&[auth_ok(mia)]);
let (code, _, _) = invoke_with(
&["provision", "user:mia", &mia_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK && api.calls.len() == 1,
"a settled group is overridden on the next issue",
)?;
// remove drops a pending record with its mapping
let noor = "77777777-7777-7777-7777-777777777777";
let noor_path = dir.join("noor.jwt").to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(noor), (500, json!({}))]);
invoke_with(
&["provision", "user:noor", &noor_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
let mut api = MockApi::new(&[(200, json!({}))]);
let (code, _, _) = invoke(&["remove", "user:noor"], &map_file, &mut api);
ensure(
code == EXIT_OK && pending(&map_file)?.is_empty(),
"remove keeps a pending record",
)?;
// a pending_acl that is not a list of distinct mapped keys is refused untouched
let pending_map = dir.join("pending.json");
for map in [
json!({ "version": 1, "clients": {}, "pending_acl": ["user:x"] }),
json!({ "version": 1, "clients": { "user:x": CLIENT_A }, "pending_acl": ["user:x", "user:x"] }),
json!({ "version": 1, "clients": { "user:x": CLIENT_A }, "pending_acl": "user:x" }),
json!({ "version": 1, "clients": { "user:x": CLIENT_A }, "pending_acl": [1] }),
] {
let text = map.to_string();
write_private_atomically(&pending_map, text.as_bytes())?;
let mut api = MockApi::new(&[]);
let (code, _, _) = invoke(&["provision", "user:x", &jwt_path], &pending_map, &mut api);
ensure(
code == EXIT_CONFIG
&& fs::read_to_string(&pending_map)? == text
&& api.calls.is_empty(),
&format!("the map {text} was accepted"),
)?;
}
Ok(())
}
/// The Embed-not-enabled refusal: `cap`, `usage`, `usage-all` and `acl` exit 78 with the fixed
/// line; `provision` still provisions and writes the client JWT, keeps the default group
/// pending with the fixed stderr line, and a provision after the team enables Embed applies it.
fn embed_not_enabled_checks(dir: &Path) -> Result<(), ToolError> {
let map_file = dir.join("embed.json");
let refusal = (
200,
json!({ "error": { "message": EMBED_NOT_ENABLED_MESSAGE } }),
);
let pia_path = dir.join("pia.jwt").to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(CLIENT_A), acl_answer(CLIENT_A, ACL_GROUP_ISOLATED)]);
let (code, _, stderr) = invoke_with(
&["provision", "user:pia", &pia_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK,
&format!("provision before the refusal: {stderr}"),
)?;
for args in [
vec!["cap", "user:pia", "--monthly", "1"],
vec!["usage", "user:pia"],
vec!["usage-all"],
vec!["acl", "user:pia", ACL_GROUP_ISOLATED],
] {
let mut api = MockApi::new(std::slice::from_ref(&refusal));
let (code, stdout, stderr) =
invoke_with(&args, &map_file, ACL_GROUP_ISOLATED, &mut api);
ensure(
code == EXIT_CONFIG
&& stdout.is_empty()
&& stderr == format!("{EMBED_NOT_ENABLED_LINE}\n"),
&format!("{args:?} while Embed isn't enabled: {code} {stderr}"),
)?;
}
let quinn_file = dir.join("quinn.jwt");
let quinn_path = quinn_file.to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(CLIENT_B), refusal.clone()]);
let (code, stdout, stderr) = invoke_with(
&["provision", "user:quinn", &quinn_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK
&& stdout == format!("{{\"client_id\":\"{CLIENT_B}\"}}\n")
&& stderr == format!("{EMBED_PENDING_LINE}\n"),
&format!("provision while Embed isn't enabled: {code} {stdout} {stderr}"),
)?;
ensure(
api.calls.len() == 2 && api.calls[1].path == ACL_PATH,
"provision while Embed isn't enabled did not try the group",
)?;
ensure(
fs::read_to_string(&quinn_file)? == format!("{}\n", jwt(CLIENT_B))
&& pending(&map_file)? == vec!["user:quinn".to_string()],
"provision while Embed isn't enabled wrote no client JWT or dropped the record",
)?;
let mut api = MockApi::new(&[auth_ok(CLIENT_B), acl_answer(CLIENT_B, ACL_GROUP_ISOLATED)]);
let (code, _, stderr) = invoke_with(
&["provision", "user:quinn", &quinn_path],
&map_file,
ACL_GROUP_ISOLATED,
&mut api,
);
ensure(
code == EXIT_OK
&& stderr.is_empty()
&& pending(&map_file)?.is_empty()
&& api.calls[1].body
== Some(json!({ "client_id": CLIENT_B, "acl_group": ACL_GROUP_ISOLATED })),
&format!("provision after Embed was enabled: {stderr}"),
)
}
/// The `status` command: `GET /network/embed` with the root credential, printed as the fixed
/// line for an enabled and a not enabled network; a refusal exits 78; a server without the
/// route and an invalid answer exit 1.
fn embed_status_checks(dir: &Path) -> Result<(), ToolError> {
let map_file = dir.join("status.json");
for (answer, line) in [
(
json!({ "enabled": true, "client_limit": 5000, "active_client_count": 1234 }),
"embed enabled: yes | client limit: 5000 | active clients: 1234\n",
),
(
json!({ "enabled": false, "client_limit": 100, "active_client_count": 0 }),
"embed enabled: no | client limit: 100 | active clients: 0\n",
),
] {
let mut api = MockApi::new(&[(200, answer)]);
let (code, stdout, stderr) = invoke(&["status"], &map_file, &mut api);
ensure(
code == EXIT_OK && stdout == line && stderr.is_empty(),
&format!("status printed {stdout} {stderr}"),
)?;
ensure(
api.calls.len() == 1
&& api.calls[0].method == "GET"
&& api.calls[0].path == EMBED_PATH
&& api.calls[0].query.is_empty(),
"the status request is not GET /network/embed",
)?;
}
let mut api = MockApi::new(&[(
200,
json!({ "error": { "message": "Invalid credential." } }),
)]);
let (code, stdout, stderr) = invoke(&["status"], &map_file, &mut api);
ensure(
code == EXIT_CONFIG
&& stdout.is_empty()
&& stderr.contains("Invalid credential.")
&& stderr.matches('\n').count() == 1,
&format!("status on a refusal: {code} {stderr}"),
)?;
let mut api = MockApi::new(&[(401, json!({}))]);
ensure(
invoke(&["status"], &map_file, &mut api).0 == EXIT_CONFIG,
"status with a refused root credential",
)?;
let mut api = MockApi::new(&[(404, json!({}))]);
let (code, _, stderr) = invoke(&["status"], &map_file, &mut api);
ensure(
code == EXIT_FAILURE && stderr == format!("{EMBED_UNSUPPORTED_MESSAGE}\n"),
&format!("status on a server without Embed enablement: {code} {stderr}"),
)?;
for answer in [
json!({ "enabled": true }),
json!({ "enabled": "yes", "client_limit": 1, "active_client_count": 1 }),
json!({ "enabled": true, "client_limit": -1, "active_client_count": 0 }),
json!({ "enabled": true, "client_limit": 1.5, "active_client_count": 0 }),
json!({ "enabled": 1, "client_limit": 1, "active_client_count": 1 }),
json!({ "enabled": true, "client_limit": "1", "active_client_count": 1 }),
] {
let mut api = MockApi::new(&[(200, answer.clone())]);
let (code, stdout, _) = invoke(&["status"], &map_file, &mut api);
ensure(
code == EXIT_FAILURE && stdout.is_empty(),
&format!("status accepted {answer}"),
)?;
}
Ok(())
}
/// The unmapped-key and 404 lines.
fn failure_text_checks(dir: &Path) -> Result<(), ToolError> {
let map_file = dir.join("texts.json");
for args in [
vec!["cap", "user:nobody", "--monthly", "1"],
vec!["usage", "user:nobody"],
vec!["remove", "user:nobody"],
vec!["acl", "user:nobody", "default"],
] {
let mut api = MockApi::new(&[]);
let (code, _, stderr) = invoke(&args, &map_file, &mut api);
ensure(
code == EXIT_CONFIG
&& stderr == format!("{UNMAPPED_MESSAGE}\n")
&& api.calls.is_empty(),
&format!("{args:?} for an unmapped key: {stderr}"),
)?;
}
let olga_path = dir.join("olga.jwt").to_string_lossy().to_string();
let mut api = MockApi::new(&[auth_ok(CLIENT_A)]);
invoke(&["provision", "user:olga", &olga_path], &map_file, &mut api);
for (args, route) in [
(vec!["cap", "user:olga", "--monthly", "1"], CAP_PATH),
(vec!["usage", "user:olga"], CAP_PATH),
(vec!["usage-all"], CAPS_PATH),
] {
let mut api = MockApi::new(&[(404, json!({}))]);
let (code, _, stderr) = invoke(&args, &map_file, &mut api);
ensure(
code == EXIT_FAILURE
&& stderr
== format!(
"{route} answered 404: the server predates the data-cap routes\n"
),
&format!("{args:?} on a server without the cap routes: {stderr}"),
)?;
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn self_test_passes() {
let mut out = Vec::new();
let mut err = Vec::new();
let code = run(&["--self-test".to_string()], &mut out, &mut err);
assert_eq!(code, EXIT_OK, "{}", String::from_utf8_lossy(&err));
assert_eq!(
String::from_utf8_lossy(&out),
"embed backend tool self-test passed\n"
);
}
#[test]
fn usage_errors_exit_78() {
let mut out = Vec::new();
let mut err = Vec::new();
assert_eq!(
run(&["--unknown".to_string()], &mut out, &mut err),
EXIT_CONFIG
);
assert!(out.is_empty());
}
}