Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
use serde::Deserialize;
use std::path::{Path, PathBuf};
use strum::IntoStaticStr;
use thiserror::Error;
use tokio::sync::mpsc::{Receiver, channel};
use url::Url;
use super::ports::FsRepo;
/// Name of the file used to persist the bundle root path across restarts.
const BUNDLE_ROOT_FILE: &str = "bundle_root";
const EMBEDDED_BUNDLE_MARKER: &str = "embedded";
/// Swappable root directory for serving frontend assets.
pub(crate) enum BundleRoot {
/// No selection was persisted; legacy completed downloads may be recovered.
Uninitialized,
/// Explicitly selected embedded assets, including after an OTA revocation.
Embedded,
/// Serve files from an applied OTA directory.
Ota(PathBuf),
}
impl BundleRoot {
/// Create an empty bundle root (no OTA update applied).
pub(crate) fn new() -> Self {
Self::Uninitialized
}
/// Create a bundle root pointing to the given path.
pub(crate) fn from_path(path: PathBuf) -> Self {
Self::Ota(path)
}
/// Load persisted bundle root from the given cache directory.
pub(crate) async fn load(cache_dir: &Path, fs: &impl FsRepo) -> Self {
let persist_path = cache_dir.join(BUNDLE_ROOT_FILE);
tracing::debug!("Loading bundle root from {persist_path:?}");
match fs.read_to_string(&persist_path).await {
Ok(contents) => {
if contents.trim() == EMBEDDED_BUNDLE_MARKER {
return Self::Embedded;
}
// Preserve compatibility with the original absolute-path marker.
let path = PathBuf::from(contents.trim());
let index = path.join("index.html");
if fs.read_to_string(&index).await.is_ok() {
tracing::debug!("Restored bundle root: {path:?}");
Self::Ota(path)
} else {
tracing::warn!(
"Persisted bundle root {path:?} missing index.html at {index:?}"
);
if let Err(e) = fs.remove_file(&persist_path).await {
tracing::debug!("Failed to remove stale bundle_root file: {e}");
}
Self::Uninitialized
}
}
Err(e) => {
tracing::debug!("No persisted bundle root: {e}");
Self::Uninitialized
}
}
}
/// Persist the bundle root path so it survives app restarts.
pub(crate) async fn persist(
&self,
cache_dir: &Path,
fs: &impl FsRepo,
) -> Result<(), std::io::Error> {
let persist_path = cache_dir.join(BUNDLE_ROOT_FILE);
match self {
Self::Ota(root) => {
tracing::debug!("Persisting bundle root {root:?} to {persist_path:?}");
fs.write(&persist_path, root.to_string_lossy().as_bytes())
.await
}
Self::Embedded => {
fs.create_dir_all(cache_dir).await?;
fs.write(&persist_path, EMBEDDED_BUNDLE_MARKER.as_bytes())
.await
}
Self::Uninitialized => fs.remove_file(&persist_path).await,
}
}
/// Get the current bundle root path, if any.
pub(crate) fn path(&self) -> Option<&Path> {
match self {
Self::Ota(path) => Some(path),
Self::Uninitialized | Self::Embedded => None,
}
}
/// Read the bundle manifest inside the bundle root.
pub(crate) async fn manifest(&self, fs: &impl FsRepo) -> Option<BundleManifest> {
let manifest_path = self.path()?.join("bundle-manifest.json");
BundleManifest::read(&manifest_path, fs).await
}
}
/// Metadata generated with each JavaScript bundle build.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct BundleManifest {
/// Manifest schema version.
pub schema_version: u64,
/// Monotonic JavaScript bundle build number.
pub bundle_build: u64,
/// Minimum native app build that can safely run this bundle.
pub min_native_build: u64,
/// Independent mobile build minima for schema 3 bundles.
#[serde(default)]
pub min_native_builds: Option<MobileBuildMinima>,
/// Short git SHA used to build the bundle.
pub git_sha: Option<String>,
/// Application package version used for the bundle.
pub app_version: String,
}
/// Independent native build requirements for a shared bundle.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
pub struct MobileBuildMinima {
/// Android versionCode.
pub android: u64,
/// iOS CFBundleVersion.
pub ios: u64,
}
impl BundleManifest {
/// Select a native minimum without comparing independent platform numbers.
pub fn minimum_for(&self, target: Target) -> Option<u64> {
match (self.schema_version, &self.min_native_builds, target) {
(2, None, Target::Android) => None,
(2, None, _) => Some(self.min_native_build),
(3, Some(builds), Target::Android) => Some(builds.android),
(3, Some(builds), Target::Ios) => Some(builds.ios),
_ => None,
}
}
/// Read and validate a bundle manifest from disk.
pub async fn read(path: &Path, fs: &impl FsRepo) -> Option<Self> {
let mut manifest = fs
.read_to_string(path)
.await
.ok()
.and_then(|s| serde_json::from_str::<Self>(&s).ok())?;
let target = if cfg!(target_os = "android") {
Target::Android
} else if cfg!(target_os = "ios") {
Target::Ios
} else {
Target::Linux
};
manifest.min_native_build = manifest.minimum_for(target)?;
Some(manifest)
}
}
/// the bounded size of mpsc channels
const MPSC_CHAN_SIZE: usize = 10;
/// Native application metadata reported by the host platform.
#[derive(Debug, Clone)]
pub struct NativeAppInfo {
/// The native app build number.
pub native_build: u64,
/// CPU architecture.
pub arch: Arch,
/// Operating system target.
pub target: Target,
}
/// Application metadata sent to the update server.
#[derive(Debug, Clone)]
pub struct AppInfo {
/// The current effective JS bundle build.
pub current_bundle_build: u64,
/// The native app build number.
pub native_build: u64,
/// CPU architecture.
pub arch: Arch,
/// Operating system target.
pub target: Target,
}
/// The possible input desktop operating systems
/// See https://v2.tauri.app/plugin/updater/#dynamic-update-server
#[derive(Debug, Clone, Copy, IntoStaticStr)]
#[strum(serialize_all = "lowercase")]
pub enum Target {
/// the requesting client is on linux
Linux,
/// the requesting client is on Windows
Windows,
/// the requesting client is on Darwin/MacOS
Darwin,
/// the requesting client is on ios
Ios,
/// the requesting client is on android
Android,
}
/// The possible input architechtures
/// See https://v2.tauri.app/plugin/updater/#dynamic-update-server
#[derive(Debug, Clone, Copy, IntoStaticStr)]
#[strum(serialize_all = "lowercase")]
pub enum Arch {
/// the x86 architecture
X86_64,
/// this is an old and mostly deprecated system architecture
/// but it technically could be sent
I686,
/// most phones and apple devices use this arch
Aarch64,
/// predecessor to the more modern arm architecture
Armv7,
}
/// Action returned by the bundle update endpoint.
#[derive(Debug, Clone, Deserialize)]
#[serde(tag = "action", rename_all = "lowercase")]
pub enum BundleAction {
/// Download and apply a newer compatible bundle.
Update(BundleUpdate),
/// Clear the active cached OTA bundle.
Clear(BundleClear),
/// A newer bundle exists, but the installed native app build is too old.
#[serde(rename = "native_update_required")]
NativeUpdateRequired(BundleNativeUpdateRequired),
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn deserializes_native_update_required_action() {
let action: BundleAction = serde_json::from_str(
r#"{"action":"native_update_required","bundleBuild":102,"minNativeBuild":999999}"#,
)
.unwrap();
assert!(matches!(
action,
BundleAction::NativeUpdateRequired(BundleNativeUpdateRequired {
bundle_build: 102,
min_native_build: 999999,
})
));
}
}
/// A response instructing the client to clear the active OTA bundle.
#[derive(Debug, Clone, Deserialize)]
pub struct BundleClear {
/// Machine-readable clear reason.
pub reason: String,
}
/// A response telling the client that the native app must be updated first.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BundleNativeUpdateRequired {
/// The newer bundle build that could not be applied.
pub bundle_build: u64,
/// The minimum native build required by that bundle.
pub min_native_build: u64,
}
/// a struct which indicates how to update only the javascript bundle of the application
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "camelCase")]
pub struct BundleUpdate {
/// the bundle build that we are going to update to
pub bundle_build: u64,
/// minimum native build required by this bundle
pub min_native_build: u64,
/// some optional notes about the update
pub notes: Option<String>,
/// the fully qualified Url where the update bundle exists
pub url: Url,
/// the expected SHA-256 hex digest of the downloaded zip file
pub checksum: String,
}
impl BundleUpdate {
/// Convert into a download request targeting `destination`, returning a progress receiver.
pub fn into_download_request<P: AsRef<Path>>(
self,
destination: P,
) -> (DownloadBundleRequest<P>, Receiver<ProgressPercentage>) {
let (tx, rx) = channel(MPSC_CHAN_SIZE);
(
DownloadBundleRequest {
url: self.url,
destination,
on_progress: tx,
},
rx,
)
}
}
/// Tracks progress as a numerator/denominator pair.
pub struct Progress {
numerator: usize,
denominator: usize,
}
impl Progress {
/// Create a progress tracker with the given total.
pub fn from_total(total: usize) -> Self {
Progress {
numerator: 0,
denominator: total,
}
}
/// Increment the numerator by `step`.
pub fn inc_by(&mut self, step: usize) {
self.numerator += step;
}
/// Set the numerator to an absolute value.
pub fn set(&mut self, numerator: usize) {
self.numerator = numerator;
}
/// Compute the current percentage (0.0–100.0).
pub fn percentage(&self) -> ProgressPercentage {
if self.denominator == 0 {
return ProgressPercentage(0.0);
}
let pct = (self.numerator as f64 / self.denominator as f64) * 100.0;
ProgressPercentage(pct.clamp(0.0, 100.0))
}
}
/// represents a [Progress] as a percentage
/// guaranteed to be (0..=100)
#[derive(Debug, Clone, Copy, Default)]
pub struct ProgressPercentage(f64);
impl ProgressPercentage {
/// 100% progress
pub fn complete() -> Self {
Self(100.0)
}
/// Get the raw percentage value.
pub fn value(self) -> f64 {
self.0
}
}
/// Parameters for downloading a bundle zip.
#[non_exhaustive]
pub struct DownloadBundleRequest<P> {
/// URL to download the zip from.
pub url: Url,
/// Local path to write the downloaded file.
pub destination: P,
/// Channel for streaming download progress.
pub on_progress: tokio::sync::mpsc::Sender<ProgressPercentage>,
}
/// Errors that can occur during bundle download.
#[derive(Debug, Error)]
pub enum DownloadBundleError {
/// File I/O failed during download.
#[error("An error occurred reading the file")]
FileError,
/// An unexpected error occurred.
#[error("An unknown error occurred")]
OtherError,
}
/// Parameters for extracting a downloaded bundle zip.
#[non_exhaustive]
pub struct UnzipRequest {
/// the path of the zip file
pub archive_path: PathBuf,
/// the path the zip should be extracted to
pub archive_target: PathBuf,
/// a sender for the progress of the extraction
pub on_progress: tokio::sync::mpsc::Sender<ProgressPercentage>,
}
impl UnzipRequest {
/// Create a new unzip request, returning the request and a progress receiver.
pub fn new(
archive_path: PathBuf,
archive_target: PathBuf,
) -> (Self, Receiver<ProgressPercentage>) {
let (tx, rx) = channel(MPSC_CHAN_SIZE);
(
UnzipRequest {
archive_path,
archive_target,
on_progress: tx,
},
rx,
)
}
}
/// Errors that can occur during bundle extraction.
#[derive(Debug, Error)]
pub enum UnzipError {
/// The archive file was not found at the expected path.
#[error("Could not find the archive at {path}")]
ArchiveNotFound {
/// The path that was searched.
path: PathBuf,
},
/// SHA-256 digest of the downloaded file did not match.
#[error("Checksum mismatch: expected {expected}, got {actual}")]
ChecksumMismatch {
/// Expected hex digest.
expected: String,
/// Actual hex digest.
actual: String,
},
/// An I/O error occurred.
#[error(transparent)]
IoErr(#[from] std::io::Error),
/// An unexpected error occurred.
#[error("{report}")]
Other {
/// The underlying error report.
report: rootcause::Report,
},
}
impl From<rootcause::Report> for UnzipError {
fn from(report: rootcause::Report) -> Self {
Self::Other { report }
}
}
/// Top-level errors for the update state machine.
#[derive(Debug, Error)]
pub enum UpdateError {
/// The download step failed.
#[error("Failed to download the update")]
DownloadErr,
/// Extraction or checksum verification failed.
#[error("Failed to unzip the update")]
Unzip,
/// User approval could not be obtained.
#[error("Failed to grant permission to update")]
GrantErr,
/// A filesystem I/O error occurred.
#[error("An io error occurred")]
IoErr,
/// An unexpected error occurred.
#[error("An unknown error occurred")]
Other,
}
/// denotes that an update was approved
#[derive(Debug, Clone, Default)]
pub struct UpdateGranted(());
/// An available update has been found.
#[derive(Debug, Clone)]
pub struct UpdateFoundStatus {
/// The bundle update metadata.
pub bundle: BundleUpdate,
}
/// A server-side revocation requires clearing the active bundle root.
#[derive(Debug, Clone)]
pub struct ClearRequiredStatus {
/// Machine-readable clear reason.
pub reason: String,
}
/// A newer bundle exists but requires a newer native app build.
#[derive(Debug, Clone)]
pub struct NativeUpdateRequiredStatus {
/// The newer bundle build that could not be applied.
pub bundle_build: u64,
/// The minimum native build required by that bundle.
pub min_native_build: u64,
}
/// A bundle download is in progress.
#[derive(Debug, Clone)]
pub struct UpdateDownloadingStatus {
/// Proof that the user approved this download.
pub grant: UpdateGranted,
/// The bundle being downloaded.
pub update: BundleUpdate,
/// Current download progress.
pub progress: ProgressPercentage,
}
/// A bundle extraction is in progress.
#[derive(Debug, Clone)]
pub struct UnzipStatus {
/// Path to the zip archive being extracted.
pub zip_filename: PathBuf,
/// Expected bundle build in the extracted manifest.
pub expected_bundle_build: u64,
/// Expected minimum native build in the extracted manifest.
pub expected_min_native_build: u64,
/// Expected SHA-256 hex digest.
pub expected_checksum: String,
/// Current extraction progress.
pub progress: ProgressPercentage,
}
/// The update has been fully downloaded and extracted.
#[derive(Debug, Clone)]
pub struct CompletedStatus {
/// Build number from the validated bundle manifest.
pub bundle_build: u64,
/// Path to the extracted `index.html` entrypoint.
pub entrypoint: PathBuf,
}
/// Current state of the update state machine.
#[derive(Debug, Clone)]
pub enum UpdateStatus {
/// No update activity.
Idle,
/// Querying the server for available updates.
CheckingForDownload(AppInfo),
/// An update is available and awaiting approval.
UpdateFound(UpdateFoundStatus),
/// An update is available, but download is deferred until Wi-Fi or Ethernet is available.
WaitingForWifi(UpdateFoundStatus),
/// The app is already on the latest version.
NoUpdateNeeded,
/// The active cached OTA bundle must be cleared.
ClearRequired(ClearRequiredStatus),
/// A newer bundle exists but requires a newer native app build.
NativeUpdateRequired(NativeUpdateRequiredStatus),
/// The bundle zip is being downloaded.
DownloadingBundle(UpdateDownloadingStatus),
/// The downloaded zip is being extracted.
UnzippingBundle(UnzipStatus),
/// The update has been applied successfully.
Completed(CompletedStatus),
}
#[cfg(test)]
#[path = "models/test.rs"]
mod platform_test;