Skip to main content

embark_macros/
lib.rs

1//! Proc-macros for `embark`: [`embed_bytes!`], [`embed_crypt!`], and the
2//! [`Embed`](macro@Embed) derive. Re-exported from the `embark` crate under
3//! its `derive` feature; use them via `embark::embed_bytes!` etc. rather
4//! than depending on this crate directly.
5
6// docs.rs builds with `--cfg docsrs` (see each manifest's
7// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
8// every item with the feature that gates it. Nearly all of this API is
9// behind one, so without the label the rendered docs read as though it were
10// all unconditional. Inert on stable, where `docsrs` is never set.
11#![cfg_attr(docsrs, feature(doc_cfg))]
12
13mod args;
14mod build;
15mod crypt;
16mod crypt_args;
17mod derive;
18mod glob;
19mod obfuscate;
20
21use proc_macro::TokenStream;
22use quote::quote;
23
24/// Embeds a single file's bytes at build time, expanding to an
25/// [`EmbeddedBytes`](https://docs.rs/embark/*/embark/struct.EmbeddedBytes.html)
26/// (or, with no `codec` argument, a plain `include_bytes!`-style
27/// `&'static [u8]`).
28///
29/// ```ignore
30/// // Zero-cost, uncompressed -- identical to include_bytes!.
31/// static RAW: &[u8] = embark::embed_bytes!("assets/logo.png");
32///
33/// // Compressed with a specific codec.
34/// static GZ: embark::EmbeddedBytes = embark::embed_bytes!("assets/data.json", codec = deflate);
35///
36/// // Compressed with the best size/decode-speed trade among the enabled
37/// // codecs; `auto_fast` and `auto_small` move that balance either way.
38/// static BEST: embark::EmbeddedBytes = embark::embed_bytes!("assets/data.json", codec = auto);
39/// ```
40///
41/// <div class="warning">Not run as a doctest: expanding this macro needs
42/// the `embark` crate, and `embark-macros` cannot depend on it without a
43/// dependency cycle. A runnable version, embedding real files, is on
44/// [`EmbeddedBytes`](https://docs.rs/embark/*/embark/struct.EmbeddedBytes.html).</div>
45///
46/// `path` is resolved relative to the crate's `CARGO_MANIFEST_DIR`. The
47/// optional `codec = <ident>` argument names either one codec -- `store`,
48/// `deflate`, `lz4`, `snappy`, `zstd` or `lzma` -- or one of the three
49/// `auto` policies, which compress with a tier of candidates at build time
50/// and keep the smallest output among that tier:
51///
52/// | policy | candidates |
53/// |---|---|
54/// | `auto_fast` | `store`, `lz4`, `snappy` |
55/// | `auto` | those, plus `deflate` and `zstd` |
56/// | `auto_small` | those, plus `lzma` |
57///
58/// Compression runs once, here; decompression runs in the shipped binary on
59/// every access. The tiers are cut along that second axis. On a 468 KiB
60/// executable, `auto_fast` picks LZ4 at 312,340 bytes and 1,744 MB/s,
61/// `auto` picks DEFLATE at 228,157 bytes and 305 MB/s, and `auto_small`
62/// picks LZMA at 191,493 bytes and 45 MB/s. All three fall back to `store`
63/// when nothing shrinks the file.
64///
65/// A policy encodes only with its own candidates, so `auto_fast` never pays
66/// LZMA's build-time encode cost to then throw the result away.
67///
68/// **Codecs and enabled features:** the codec ident you name here must
69/// correspond to a codec feature enabled on the `embark` crate you decode
70/// with. If it isn't enabled, encoding does not fail -- the entry silently
71/// degrades to `store` (uncompressed) instead, since encoding never fails
72/// and correct but uncompressed output is still correct. Enable the
73/// matching feature (`deflate`, `lz4`, `snappy`, `zstd`, `lzma`) if you
74/// expect compression to actually happen. The `auto` policies can only pick
75/// an enabled codec by construction, and a policy whose whole tier is
76/// disabled widens to the next one rather than degrading to `store`: with
77/// only `lzma` on, `auto_fast` still compresses.
78#[proc_macro]
79pub fn embed_bytes(input: TokenStream) -> TokenStream {
80    let args = syn::parse_macro_input!(input as args::Args);
81    expand_bytes(args)
82        .unwrap_or_else(syn::Error::into_compile_error)
83        .into()
84}
85
86fn expand_bytes(args: args::Args) -> syn::Result<proc_macro2::TokenStream> {
87    let span = args.path.span();
88    let shown = args.path.value();
89    let path = build::resolve(&args.path);
90    match args.codec {
91        None => {
92            // Raw mode: zero-cost include_bytes! with an absolute path.
93            build::ensure_readable(&path, &shown, span)?;
94            let abs = build::path_str(&path, span)?;
95            Ok(quote!(::core::include_bytes!(#abs)))
96        }
97        Some(codec) => {
98            let data = build::read(&path, &shown).map_err(build::at(span))?;
99            let entry = build::build_entry(codec, &data, &shown).map_err(build::at(span))?;
100            let lit = build::bytes_literal(&entry);
101            let track = build::track_file(&path, span)?;
102            Ok(quote! {
103                {
104                    #track
105                    ::embark::EmbeddedBytes::from_entry(#lit)
106                }
107            })
108        }
109    }
110}
111
112/// Embeds a single file, encrypted at build time with ChaCha20-Poly1305 (or,
113/// with `cipher = aes`, AES-256-GCM), expanding to an
114/// [`EncryptedFile`](https://docs.rs/embark/*/embark/struct.EncryptedFile.html),
115/// generic over a type-state marker
116/// ([`EmbeddedKey`](https://docs.rs/embark/*/embark/struct.EmbeddedKey.html)
117/// or
118/// [`RuntimeKey`](https://docs.rs/embark/*/embark/struct.RuntimeKey.html))
119/// that determines which decrypt methods the resulting handle has.
120///
121/// ```ignore
122/// // Build-time embedded key (the default): obfuscation, not security --
123/// // see EncryptedFile's docs. Type is EncryptedFile<EmbeddedKey>.
124/// static SECRET: embark::EncryptedFile = embark::embed_crypt!("assets/config.enc");
125/// let plaintext = SECRET.decrypt();
126///
127/// // Runtime key: real confidentiality. No key is embedded in the binary.
128/// // Type is EncryptedFile<RuntimeKey> -- note the explicit annotation.
129/// static SEALED: embark::EncryptedFile<embark::RuntimeKey> =
130///     embark::embed_crypt!("assets/config.enc", key = runtime);
131/// let plaintext = SEALED.decrypt_with(&my_key).unwrap();
132/// ```
133///
134/// <div class="warning">Not run as a doctest: expanding this macro needs
135/// the `embark` crate, and `embark-macros` cannot depend on it without a
136/// dependency cycle. A runnable version of the embedded-key half is on
137/// [`EncryptedFile`](https://docs.rs/embark/*/embark/struct.EncryptedFile.html).
138/// The runtime-key half cannot be a doctest anywhere: `key = runtime`
139/// reads `EMBARK_KEY` from the environment at build time.</div>
140///
141/// `path` is resolved relative to `CARGO_MANIFEST_DIR`, as in
142/// [`embed_bytes!`]. Independent, comma-separated arguments may follow
143/// the path, in any order:
144///
145/// - `codec = <ident>` — compress before sealing (`store`, `deflate`,
146///   `lz4`, `snappy`, `zstd`, `lzma`, or one of `auto_fast` / `auto` /
147///   `auto_small`). Defaults to `deflate` when omitted. The `auto` policies
148///   run the same selection pass as in [`embed_bytes!`]; compression
149///   happens before sealing, so the pass reads the plaintext and the cipher
150///   sees no difference. The same feature-enablement caveat as
151///   [`embed_bytes!`] applies: if the named codec's feature isn't enabled
152///   on `embark`, the entry silently degrades to `store` instead of failing
153///   to build.
154/// - `cipher = <ident>` — the AEAD cipher to seal with: `chacha`
155///   (ChaCha20-Poly1305, the default) or `aes` (AES-256-GCM). Both share
156///   the same key/nonce/tag shape and threat model — see `EncryptedFile`'s
157///   docs. `cipher = aes` requires the `aes` feature enabled on `embark`;
158///   naming it without that feature is a build error, not a silent
159///   fallback (unlike an unavailable codec).
160/// - `key = runtime` — opt into the runtime-key mode: no key material is
161///   embedded, and the resulting handle (an `EncryptedFile<RuntimeKey>`)
162///   must be decrypted with `decrypt_with(&key)` -- it has no `decrypt()`
163///   method at all, so a binding must be explicitly typed
164///   `EncryptedFile<RuntimeKey>` (plain `EncryptedFile` defaults to
165///   `EncryptedFile<EmbeddedKey>` and will not accept it). Omitted by
166///   default, which uses the build-time embedded-key mode
167///   (**obfuscation, not security** — see `EncryptedFile`'s docs for what
168///   that means and why).
169///
170///   Cargo does not know this expansion reads `EMBARK_KEY`, so changing the
171///   key and rebuilding with no source change leaves the entry sealed under
172///   the old one, silently. Put
173///   `println!("cargo:rerun-if-env-changed=EMBARK_KEY");` in the embedding
174///   crate's `build.rs` and a key change re-seals it. A proc macro cannot
175///   register that dependency itself on stable Rust.
176#[proc_macro]
177pub fn embed_crypt(input: TokenStream) -> TokenStream {
178    let parsed = syn::parse_macro_input!(input as crypt_args::CryptArgs);
179    expand_crypt(parsed)
180        .unwrap_or_else(syn::Error::into_compile_error)
181        .into()
182}
183
184fn expand_crypt(parsed: crypt_args::CryptArgs) -> syn::Result<proc_macro2::TokenStream> {
185    let span = parsed.path.span();
186    let shown = parsed.path.value();
187    let path = build::resolve(&parsed.path);
188    let data = build::read(&path, &shown).map_err(build::at(span))?;
189    let track = build::track_file(&path, span)?;
190    let codec = parsed.codec();
191    let crypto = parsed.crypto_id();
192    let mode = match parsed.runtime_key {
193        // `KeyMode::Runtime` carries its own span, so an EMBARK_KEY failure
194        // lands on the `key = runtime` argument that asked for it rather
195        // than on the path literal every other diagnostic points at.
196        Some(key_span) => crypt::KeyMode::Runtime(key_span),
197        None => crypt::KeyMode::BuildTime,
198    };
199    let sealed = crypt::seal_file(&data, codec, crypto, mode, &shown, span)?;
200    let entry_lit = build::bytes_literal(&sealed.entry);
201    Ok(match &sealed.key {
202        Some(key) => {
203            // Emit a per-build-randomized key-reconstruction fn and hand its
204            // pointer to `with_embedded_key`. The whole thing is a block
205            // expression valid in a `static` initializer: an inner `fn` item
206            // plus a const-constructible tail call.
207            let (recon_fn, recon_name) = obfuscate::emit_key_recon(key);
208            quote! {
209                {
210                    #track
211                    #recon_fn
212                    ::embark::EncryptedFile::with_embedded_key(#entry_lit, #recon_name)
213                }
214            }
215        }
216        None => quote! {
217            {
218                #track
219                ::embark::EncryptedFile::with_runtime_key(#entry_lit)
220            }
221        },
222    })
223}
224
225/// Derives [`Embed`](https://docs.rs/embark/*/embark/trait.Embed.html) for
226/// a unit struct, embedding every file under a folder at build time.
227///
228/// ```ignore
229/// #[derive(embark::Embed)]
230/// #[embark(folder = "assets", codec = "auto", include = "*.png", exclude = "*.tmp")]
231/// struct Assets;
232///
233/// let logo = Assets::get("logo.png").unwrap();
234/// for path in Assets::iter() { /* ... */ }
235/// ```
236///
237/// <div class="warning">Not run as a doctest: expanding this macro needs
238/// the `embark` crate, and `embark-macros` cannot depend on it without a
239/// dependency cycle. A runnable version, embedding a real folder, is on
240/// [`Embed`](https://docs.rs/embark/*/embark/trait.Embed.html).</div>
241///
242/// Configured with a single `#[embark(...)]` attribute, whose keys are:
243///
244/// - `folder = "..."` (required) — the directory to embed, relative to
245///   `CARGO_MANIFEST_DIR`. Walked recursively; every file found becomes a
246///   manifest entry, keyed by its path relative to this folder (with `/`
247///   separators, even on Windows).
248/// - `codec = "..."` — compression for every embedded file: `"store"`,
249///   `"deflate"` (the default), `"lz4"`, `"snappy"`, `"zstd"`, `"lzma"`, or
250///   one of the three selection policies `"auto_fast"`, `"auto"` and
251///   `"auto_small"`, described on [`embed_bytes!`]. A policy is applied per
252///   file, so one folder can end up with a different codec per entry. It
253///   applies under `encrypt` too, on each file's plaintext.
254///   As with `embed_bytes!`, naming a codec whose feature isn't enabled on
255///   `embark` does not fail the build -- affected entries silently degrade
256///   to `store` (correct, just uncompressed).
257/// - `encrypt` — seal every embedded file with a single build-time
258///   embedded key shared by the whole derive
259///   (**obfuscation, not security** -- see `EncryptedFile`'s docs).
260///   `Embed::get` then returns files decryptable with the infallible
261///   `EncryptedFile::decrypt()`. There is currently no per-derive
262///   `key = runtime` option; use `embed_crypt!` directly for runtime-key
263///   files.
264/// - `cipher = "..."` — the AEAD cipher `encrypt` seals with: `"chacha"`
265///   (ChaCha20-Poly1305, the default) or `"aes"` (AES-256-GCM). Ignored
266///   without `encrypt`. Both share the same threat model -- see
267///   `EncryptedFile`'s docs. `cipher = "aes"` requires the `aes` feature
268///   enabled on `embark`; naming it without that feature is a build error.
269/// - `dev` — in debug builds only, `get()` reads the file live from disk
270///   (relative to `folder`) instead of returning the compiled-in copy, for
271///   fast iteration without rebuilding. Has no effect in release builds.
272///
273///   Combined with `encrypt`, a debug build serves the file as it is on
274///   disk, in the clear: the copy there was never sealed, and this mode is
275///   for a developer's own machine. The release build is unaffected.
276///
277///   It serves the files the derive embedded and nothing else: a path has
278///   to be one the manifest holds, exactly, or `get()` returns `None` just
279///   as the release build would. A file added to the folder since the last
280///   build is not served until the crate rebuilds, and one that `exclude`
281///   left out is never served. This is what keeps a development server
282///   that hands out assets by request path from handing out `../.env`.
283/// - `follow_links` — follow symbolic links (and, on Windows, junctions)
284///   found inside the folder. Off by default, and a link met without it is
285///   a build error rather than a skipped file: a link can point anywhere
286///   on the build machine, and following one that points at a key or a
287///   credential file embeds that file into the binary. That is a plausible
288///   shape for an accident and a very plausible shape for a hostile pull
289///   request. With it on, each real directory is walked once, so a link
290///   back to an ancestor ends the walk instead of never ending it.
291/// - `include = "..."` / `exclude = "..."` — glob filters over each file's
292///   path relative to `folder`; repeatable (each occurrence adds one
293///   pattern). A file is embedded when it matches no `exclude` pattern and
294///   (`include` is empty, or it matches at least one `include` pattern).
295///   `exclude` takes priority over `include`.
296///
297///   `?` matches one character other than `/`, and `*` any run of them, so
298///   a single `*` stays inside one path segment: `include = "*.png"`
299///   matches `logo.png` but not `sub/logo.png`.
300///
301///   `**` crosses `/`. As a whole segment it stands for any number of
302///   segments, zero included, which is what makes `**/*.png` the way to say
303///   "a `.png` anywhere":
304///
305///   | pattern | matches |
306///   |---|---|
307///   | `*.png` | `logo.png` |
308///   | `sub/*.png` | `sub/logo.png` |
309///   | `**/*.png` | `logo.png`, `sub/logo.png`, `a/b/logo.png` |
310///   | `sub/**` | everything under `sub/`, at any depth |
311///   | `**` | everything |
312///
313/// # Rebuilds
314///
315/// Every embedded file is registered as a build input, so editing or
316/// deleting one of them triggers a rebuild. **Adding a new file to the
317/// folder does not.** Only the files that existed when the derive last
318/// expanded are tracked, and a file that has never been seen cannot be
319/// among them. After adding a file, force the crate to rebuild -- touch
320/// any of its `.rs` files, or run `cargo clean -p <crate>`.
321#[proc_macro_derive(Embed, attributes(embark))]
322pub fn derive_embed(input: TokenStream) -> TokenStream {
323    let parsed = syn::parse_macro_input!(input as syn::DeriveInput);
324    derive::expand(&parsed)
325        .unwrap_or_else(|e| derive::error_with_stub(&parsed, &e))
326        .into()
327}