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
//! Open Packaging Conventions: parts, content types, and relationships.
//!
//! A [`Package`] keeps the original archive bytes. Parts the caller never
//! replaces are written back with their original compressed bytes, so saving
//! only changes what was edited.
mod content_types;
mod rels;
pub use content_types::ContentTypes;
pub use rels::{Relationship, Relationships, TargetMode};
use crate::error::{Error, Result};
use crate::zip::{self, Archive, Entry, WriteData};
use std::borrow::Cow;
use std::collections::HashMap;
/// Name of the content-types part.
pub const CONTENT_TYPES_PART: &str = "/[Content_Types].xml";
/// Name of the package-level relationships part.
pub const PACKAGE_RELS_PART: &str = "/_rels/.rels";
/// Well-known relationship types.
pub mod rel_type {
/// Package → main presentation part.
pub const OFFICE_DOCUMENT: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
/// ISO 29500 strict spelling of [`OFFICE_DOCUMENT`].
pub const OFFICE_DOCUMENT_STRICT: &str =
"http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument";
/// Presentation → slide.
pub const SLIDE: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
/// Presentation → slide master; slide layout → slide master.
pub const SLIDE_MASTER: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster";
/// Slide → slide layout; slide master → slide layouts.
pub const SLIDE_LAYOUT: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout";
/// Master/presentation → theme.
pub const THEME: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
/// Slide → notes slide.
pub const NOTES_SLIDE: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide";
/// Presentation → notes master.
pub const NOTES_MASTER: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster";
/// Any part → image.
pub const IMAGE: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
/// Graphic frame → chart.
pub const CHART: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
/// Any part → hyperlink target.
pub const HYPERLINK: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
/// Presentation → table styles.
pub const TABLE_STYLES: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/tableStyles";
/// SmartArt pre-rendered drawing.
pub const DIAGRAM_DRAWING: &str =
"http://schemas.microsoft.com/office/2007/relationships/diagramDrawing";
/// Slide → comments.
pub const COMMENTS: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
/// Slide → video file (`a:videoFile r:link`).
pub const VIDEO: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/video";
/// Slide → audio file (`a:audioFile r:link`).
pub const AUDIO: &str =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/audio";
/// Slide → embedded media (`p14:media r:embed`).
pub const MEDIA: &str = "http://schemas.microsoft.com/office/2007/relationships/media";
/// Package → core properties.
pub const CORE_PROPERTIES: &str =
"http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
}
/// Well-known content types.
pub mod content_type {
/// Slide part.
pub const SLIDE: &str =
"application/vnd.openxmlformats-officedocument.presentationml.slide+xml";
/// Notes slide part.
pub const NOTES_SLIDE: &str =
"application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml";
/// Relationships part.
pub const RELATIONSHIPS: &str = "application/vnd.openxmlformats-package.relationships+xml";
}
#[derive(Clone, Debug)]
enum PartData {
/// Still the bytes from the source archive.
Original(Entry),
/// Replaced or newly created, with the package generation of the write.
Modified(std::sync::Arc<Vec<u8>>, u64),
}
#[derive(Clone, Debug)]
struct Part {
/// Normalized part name with a leading slash.
name: String,
/// Name inside the zip (original spelling, no leading slash).
zip_name: String,
data: PartData,
}
/// Pseudo-random numbers for naming new parts and ids.
///
/// Peers editing one presentation concurrently must not mint the same part
/// name, relationship id, slide id, or shape id, or their merged edits would
/// collide. Sequential allocation ("the next free number") collides almost
/// surely; random allocation from a wide range practically never does.
#[derive(Debug)]
pub struct IdSource(std::sync::atomic::AtomicU64);
impl IdSource {
/// A source seeded with `seed` (use a value unique to the editing peer).
pub fn new(seed: u64) -> Self {
Self(std::sync::atomic::AtomicU64::new(seed))
}
/// The next number in `range` (splitmix64).
pub fn next_in(&self, range: std::ops::Range<u64>) -> u64 {
let state = self
.0
.fetch_add(0x9E37_79B9_7F4A_7C15, std::sync::atomic::Ordering::Relaxed)
.wrapping_add(0x9E37_79B9_7F4A_7C15);
let mut z = state;
z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
z ^= z >> 31;
range.start + z % (range.end - range.start).max(1)
}
}
/// An OPC package (a `.pptx` file).
#[derive(Clone)]
pub struct Package {
source: std::sync::Arc<Vec<u8>>,
parts: Vec<Part>,
/// Lower-cased part name → index into `parts`.
index: HashMap<String, usize>,
content_types: ContentTypes,
/// Bumped on every write, so part identities never repeat.
generation: u64,
/// Random naming for new parts and ids (collaborative editing).
ids: Option<std::sync::Arc<IdSource>>,
}
/// Normalizes a part name: leading slash, `/` separators, no `.`/`..` segments.
pub fn normalize_part_name(name: &str) -> String {
let mut segments: Vec<&str> = Vec::new();
for seg in name.split(['/', '\\']) {
match seg {
"" | "." => {}
".." => {
segments.pop();
}
s => segments.push(s),
}
}
format!("/{}", segments.join("/"))
}
/// Directory of a part name (`/ppt/slides/slide1.xml` → `/ppt/slides`).
pub fn part_dir(name: &str) -> &str {
name.rfind('/').map_or("", |i| &name[..i])
}
/// The relationships part that belongs to `part`.
pub fn rels_part_name(part: &str) -> String {
let dir = part_dir(part);
let file = &part[dir.len() + 1..];
format!("{dir}/_rels/{file}.rels")
}
/// Decodes `%XX` escapes in a relationship target.
pub fn percent_decode(s: &str) -> String {
if !s.contains('%') {
return s.to_owned();
}
let hex = |c: u8| (c as char).to_digit(16).map(|d| d as u8);
let b = s.as_bytes();
let mut out = Vec::with_capacity(b.len());
let mut i = 0;
while i < b.len() {
if b[i] == b'%'
&& i + 2 < b.len()
&& let (Some(hi), Some(lo)) = (hex(b[i + 1]), hex(b[i + 2]))
{
out.push(hi << 4 | lo);
i += 3;
continue;
}
out.push(b[i]);
i += 1;
}
String::from_utf8_lossy(&out).into_owned()
}
/// Resolves a relationship target relative to its source part.
pub fn resolve_target(source_part: &str, target: &str) -> String {
let target = percent_decode(target);
let target = target.split('#').next().unwrap_or("");
if target.starts_with('/') {
normalize_part_name(target)
} else {
normalize_part_name(&format!("{}/{}", part_dir(source_part), target))
}
}
/// Computes a relative reference from `source_part`'s directory to `target_part`.
pub fn relative_target(source_part: &str, target_part: &str) -> String {
let from: Vec<&str> = part_dir(source_part)
.split('/')
.filter(|s| !s.is_empty())
.collect();
let to: Vec<&str> = target_part.split('/').filter(|s| !s.is_empty()).collect();
let common = from.iter().zip(&to).take_while(|(a, b)| a == b).count();
let mut parts: Vec<&str> = std::iter::repeat_n("..", from.len() - common).collect();
parts.extend(&to[common..]);
parts.join("/")
}
impl Package {
/// Opens a package from the bytes of a `.pptx` file.
pub fn open(bytes: Vec<u8>) -> Result<Self> {
let source = std::sync::Arc::new(bytes);
let archive = Archive::parse(&source)?;
let mut parts = Vec::with_capacity(archive.entries().len());
let mut index = HashMap::new();
for entry in archive.entries() {
let name = normalize_part_name(&entry.name);
let key = name.to_ascii_lowercase();
if index.contains_key(&key) {
// Duplicate names are invalid OPC; keep the first occurrence.
continue;
}
index.insert(key, parts.len());
parts.push(Part {
name,
zip_name: entry.name.clone(),
data: PartData::Original(entry.clone()),
});
}
drop(archive);
let mut pkg = Self {
source,
parts,
index,
content_types: ContentTypes::default(),
generation: 0,
ids: None,
};
let ct_bytes = pkg
.read(CONTENT_TYPES_PART)
.map_err(|_| Error::MissingPart("[Content_Types].xml (not an Office package)".into()))?
.into_owned();
pkg.content_types = ContentTypes::parse(&ct_bytes)?;
Ok(pkg)
}
/// Whether a part exists (case-insensitive, as OPC requires).
pub fn has_part(&self, name: &str) -> bool {
self.index
.contains_key(&normalize_part_name(name).to_ascii_lowercase())
}
fn part(&self, name: &str) -> Option<&Part> {
self.index
.get(&normalize_part_name(name).to_ascii_lowercase())
.map(|&i| &self.parts[i])
}
/// The canonical spelling of a part name as stored in the package.
pub fn canonical_name(&self, name: &str) -> Option<&str> {
self.part(name).map(|p| p.name.as_str())
}
/// Part names in package order.
pub fn part_names(&self) -> impl Iterator<Item = &str> {
self.parts.iter().map(|p| p.name.as_str())
}
/// Reads (inflating if needed) the bytes of a part.
pub fn read(&self, name: &str) -> Result<Cow<'_, [u8]>> {
let part = self
.part(name)
.ok_or_else(|| Error::MissingPart(name.to_owned()))?;
match &part.data {
PartData::Original(entry) => {
let raw = &self.source
[entry.data_start..entry.data_start + entry.compressed_size as usize];
Ok(Cow::Owned(zip::inflate_entry(entry, raw)?))
}
PartData::Modified(bytes, _) => Ok(Cow::Borrowed(bytes.as_slice())),
}
}
/// Reads at most the first `max` bytes of a part (inflating only those),
/// for file headers.
pub fn read_prefix(&self, name: &str, max: usize) -> Result<Cow<'_, [u8]>> {
let part = self
.part(name)
.ok_or_else(|| Error::MissingPart(name.to_owned()))?;
match &part.data {
PartData::Original(entry) => {
let raw = &self.source
[entry.data_start..entry.data_start + entry.compressed_size as usize];
Ok(Cow::Owned(zip::inflate_prefix(entry, raw, max)?))
}
PartData::Modified(bytes, _) => Ok(Cow::Borrowed(&bytes[..max.min(bytes.len())])),
}
}
/// Uncompressed size of a part, without inflating it.
pub fn part_size(&self, name: &str) -> Option<u64> {
self.part(name).map(|p| match &p.data {
PartData::Original(e) => e.uncompressed_size,
PartData::Modified(b, _) => b.len() as u64,
})
}
/// A token identifying a part's current bytes. Two states of the same
/// package hold identical bytes for a part when their tokens are equal.
pub fn part_identity(&self, name: &str) -> Option<(bool, usize)> {
self.part(name).map(|p| match &p.data {
PartData::Original(e) => (false, e.data_start),
PartData::Modified(_, generation) => (true, *generation as usize),
})
}
/// Whether a part was replaced or created since opening.
pub fn is_modified(&self, name: &str) -> bool {
self.part(name)
.is_some_and(|p| matches!(p.data, PartData::Modified(..)))
}
/// Replaces (or creates) a part. New parts need a content type, either an
/// override registered here or a default for their extension.
pub fn write(&mut self, name: &str, bytes: Vec<u8>, content_type: Option<&str>) {
let name = normalize_part_name(name);
let key = name.to_ascii_lowercase();
self.generation += 1;
let data = PartData::Modified(std::sync::Arc::new(bytes), self.generation);
match self.index.get(&key) {
Some(&i) => self.parts[i].data = data,
None => {
self.index.insert(key, self.parts.len());
self.parts.push(Part {
zip_name: name[1..].to_owned(),
name: name.clone(),
data,
});
}
}
if let Some(ct) = content_type {
self.content_types.set_override(&name, ct);
}
}
/// Removes a part (and its content-type override).
pub fn delete(&mut self, name: &str) {
let key = normalize_part_name(name).to_ascii_lowercase();
if let Some(i) = self.index.remove(&key) {
let removed = self.parts.remove(i);
self.content_types.remove_override(&removed.name);
for v in self.index.values_mut() {
if *v > i {
*v -= 1;
}
}
}
}
/// The package's content types.
pub fn content_types(&self) -> &ContentTypes {
&self.content_types
}
/// Replaces the content types (written out on the next save).
pub fn set_content_types(&mut self, mut content_types: ContentTypes) {
content_types.mark_dirty();
self.content_types = content_types;
}
/// Mutable access to content types.
pub fn content_types_mut(&mut self) -> &mut ContentTypes {
&mut self.content_types
}
/// Content type of a part.
pub fn content_type(&self, name: &str) -> Option<&str> {
self.content_types.lookup(&normalize_part_name(name))
}
/// Parses the relationships of `source_part` (empty if it has none).
pub fn rels(&self, source_part: &str) -> Result<Relationships> {
let rels_name = if source_part == "/" {
PACKAGE_RELS_PART.to_owned()
} else {
rels_part_name(source_part)
};
let rels = if self.has_part(&rels_name) {
Relationships::parse(source_part, &self.read(&rels_name)?)?
} else {
Relationships::empty(source_part)
};
Ok(rels.with_ids(self.ids.clone()))
}
/// Writes the relationships of a part back to the package.
pub fn write_rels(&mut self, rels: &Relationships) {
let name = if rels.source() == "/" {
PACKAGE_RELS_PART.to_owned()
} else {
rels_part_name(rels.source())
};
self.write(&name, rels.to_bytes(), None);
self.content_types
.ensure_default("rels", content_type::RELATIONSHIPS);
}
/// Picks an unused part name `"{prefix}{n}{suffix}"`: the smallest n ≥ 1,
/// or a random one when [`Package::use_random_ids`] is on.
pub fn unique_part_name(&self, prefix: &str, suffix: &str) -> String {
if let Some(ids) = &self.ids {
loop {
let name = format!("{prefix}{}{suffix}", ids.next_in(1_000_000..1_000_000_000));
if !self.has_part(&name) {
return name;
}
}
}
(1..)
.map(|n| format!("{prefix}{n}{suffix}"))
.find(|n| !self.has_part(n))
.expect("unbounded search")
}
/// Names new parts and relationships, and new slides and shapes number
/// their ids, from `ids` instead of the next free number.
pub fn use_random_ids(&mut self, ids: std::sync::Arc<IdSource>) {
self.ids = Some(ids);
}
/// The random id source, when [`Package::use_random_ids`] is on.
pub fn ids(&self) -> Option<&std::sync::Arc<IdSource>> {
self.ids.as_ref()
}
/// The main presentation part (target of the package's officeDocument relationship).
pub fn main_part(&self) -> Result<String> {
let rels = self.rels("/")?;
rels.iter()
.find(|r| {
r.rel_type == rel_type::OFFICE_DOCUMENT
|| r.rel_type == rel_type::OFFICE_DOCUMENT_STRICT
})
.map(|r| rels.resolve(r))
.or_else(|| {
self.has_part("/ppt/presentation.xml")
.then(|| "/ppt/presentation.xml".to_owned())
})
.ok_or_else(|| Error::MissingPart("officeDocument relationship".into()))
}
/// Serializes the package. Untouched parts keep their original bytes.
pub fn save(&self) -> Result<Vec<u8>> {
let mut writer = zip::Writer::new();
let ct_original = self.part(CONTENT_TYPES_PART).and_then(|p| match &p.data {
PartData::Original(entry) if !self.content_types.is_dirty() => Some((p, entry)),
_ => None,
});
match ct_original {
Some((part, entry)) => {
let raw = &self.source
[entry.data_start..entry.data_start + entry.compressed_size as usize];
writer.add(&part.zip_name, WriteData::Raw { entry, raw })?;
}
None => {
let ct_bytes = self.content_types.to_bytes();
writer.add(
"[Content_Types].xml",
WriteData::Fresh {
data: &ct_bytes,
compress: true,
},
)?;
}
}
for part in &self.parts {
if part.name.eq_ignore_ascii_case(CONTENT_TYPES_PART) {
continue;
}
match &part.data {
PartData::Original(entry) => {
let raw = &self.source
[entry.data_start..entry.data_start + entry.compressed_size as usize];
writer.add(&part.zip_name, WriteData::Raw { entry, raw })?;
}
PartData::Modified(bytes, _) => {
writer.add(
&part.zip_name,
WriteData::Fresh {
data: bytes,
compress: should_compress(&part.name),
},
)?;
}
}
}
writer.finish()
}
}
/// Already-compressed media gains nothing from DEFLATE.
fn should_compress(name: &str) -> bool {
let ext = name.rsplit('.').next().unwrap_or("").to_ascii_lowercase();
!matches!(
ext.as_str(),
"png"
| "jpg"
| "jpeg"
| "gif"
| "mp4"
| "m4a"
| "mp3"
| "zip"
| "xlsx"
| "docx"
| "pptx"
| "wdp"
)
}
#[cfg(test)]
mod test;