# craft-opc

Open Packaging Conventions (ECMA-376 Part 2): the ZIP container that DOCX, XLSX and PPTX files
share. It replaces the package layer each Craft app carried for its own format (WordCraft's
`docx::package`, GridCraft's `xlsx::package`, DeckCraft's `pptx::opc`).

What the parts hold stays with each format's crate. Parts are read with `zip` and XML with
`craft-xml`.

```rust
use craft_opc::{Limits, Package, PackageOut, RelsOut};

let mut out = PackageOut::default();
out.xml_part("xl/workbook.xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml", b"<workbook/>".to_vec());
out.binary("xl/media/image1.png", "image/png", vec![0x89, b'P', b'N', b'G']);
let mut rels = RelsOut::default();
rels.add("officeDocument", "xl/workbook.xml", false);
out.rels("", &rels);
let bytes = out.finish().unwrap();

let limits = Limits::new(10_000, 64 << 20, 256 << 20);
let pkg = Package::open(&bytes, &limits).unwrap();
let main = pkg.rels("").first("officeDocument").map(|r| r.target.clone()).unwrap();
assert_eq!(main, "xl/workbook.xml");
assert_eq!(pkg.content_types().of("xl/media/image1.png"), Some("image/png"));
assert!(pkg.get("XL/Workbook.xml").is_some());
```

## Reading

Two readers, because the apps read in two ways:

| | `Package` | `LazyPackage` |
| --- | --- | --- |
| Inflates | every part, in `open` | a part when `read` asks for it |
| Borrows the file's bytes | no | yes |
| A part over a limit | refuses the package, or is left out (`Limits::oversized`) | is that read's error |
| A damaged entry | left out with a logged warning | is that read's error, and ends the budget (`read_optional_limited`: costs only its own allowance) |
| Came from | WordCraft (refuse), DeckCraft (leave out) | GridCraft |

Both look parts up without regard to case, leading `/` or `\` for `/`.

### Limits

`Limits` has no defaults: each format keeps its own numbers.

| Limit | Checked | Error |
| --- | --- | --- |
| `max_entries` | from the end records, before `zip` indexes the entries (`check_entry_count`), and again on the count `zip` found | `TooManyEntries`, `TooManyEndRecords` |
| `max_part` | on the declared size, then on what is inflated (a read stops one byte past it) | `PartTooLarge` |
| `max_total` | on the bytes kept | `PackageTooLarge` |
| `max_work` | on the bytes inflated, kept or not: an entry inflates in full before its checksum is compared, so entries that fail it would otherwise be free | `PackageTooLarge` |

`Limits::new` sets `max_work` to `max_total` and refuses oversized parts. At most 16 MiB is
reserved for a part before its bytes arrive, whatever size it declares.

`check_entry_count` is a bytes-only check of what the end of central directory records declare.
It does not validate the archive; `zip` does.

### Names and relationships

- `Package::canonical(name)` is the stored spelling. When entries differ only in case, they are
  one part: the spelling a relationship names is kept, else the first in byte order.
- `Rels`: `by_id`, `target`, `first(type)`, `all(type)`. A type is matched by its full URI or
  by its last segment, so `first("image")` finds the transitional and the strict spelling
  (`type_is`). The first relationship of a repeated id wins.
- `Rel::target` is a part name for an internal target and the URL for an external one;
  `target_raw` is what the file wrote. A target is looked up as written, then with `%hh`
  escapes decoded; when the package has the part, `target` is its stored spelling.
- `resolve(dir, target)` drops a fragment and cannot climb out of the package. `relative(from, to)`
  is its inverse.
- `ContentTypes::of(part)`: Override by part name, then Default by extension.

A missing or unreadable relationships or content types part reads as empty, with a logged
warning for an unreadable one.

## Writing

- `PackageOut`: `xml_part` (with an Override), `binary` (a Default for its extension, or an
  Override when the extension already has another type), `raw`, `rels`; `finish` writes
  `[Content_Types].xml` first and leaves out a second part under a name already written.
- `RelsOut`: `add` reuses the relationship already made for a type, target and mode; `add_new`
  never does. Ids are `rId1`, `rId2`…
- `ZipOut` and `zip_entries` for a writer that builds its own content types. Output is
  deterministic: deflate level 6, one fixed timestamp. Names with an already-compressed
  extension are stored (`compression_for`).

## Not here

- Flat OPC (`pkg:package` XML) and encrypted packages (a compound file holding
  `EncryptedPackage`): still with the apps.
- A full ZIP preflight (overlapping entries, lying offsets): `check_entry_count` covers the
  entry count only.