rapidproto-build 0.1.0-alpha.2

Generates RapidProto's Rust decoders for Protobuf schemas in a build script, without protoc.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
//! Generates Rust decoders for Protobuf schemas in a build script, without `protoc`.
//!
//! The decoders use the [`rapidproto`] runtime. Add `rapidproto` to your dependencies and
//! `rapidproto-build` to your build dependencies, both pinned to the same version with `=`. The
//! runtime's [`example`] module shows a schema and the code generated for it.
//!
//! Use [`Config`] in `build.rs`:
//!
//! ```no_run
//! // build.rs
//! rapidproto_build::Config::new("crate::schema")
//!     .include("proto")
//!     .compile(&["proto/message.proto"])
//!     .expect("generate decoders");
//! ```
//!
//! [`Config::compile`] writes `message.rs` to `OUT_DIR`, named after the first entry. Include it at the
//! path you passed to [`Config::new`], and decode with it:
//!
//! ```ignore
//! mod schema {
//!     include!(concat!(env!("OUT_DIR"), "/message.rs"));
//! }
//!
//! // For `package shop;` and `message Order` in message.proto:
//! let arena = rapidproto::Arena::new();
//! let order = schema::arena::shop::Order::decode(&input, &arena)?;
//! ```
//!
//! `Config` generates arena decoders by default. It can also generate [stream decoders], apply a
//! [decode profile], and implement [`serde::Serialize`]. To get the code as a string instead of a
//! file, use [`Config::generate`]. Imports of the well-known types, such as
//! `google/protobuf/timestamp.proto`, resolve without the files.
//!
//! The command-line tool `rapidproto-rust` generates the same code, for projects that commit it.
//! Install it with `cargo install rapidproto-build --version 0.1.0-alpha.2`, and see
//! `rapidproto-rust --help` for its options.
//!
//! # How the generator runs
//!
//! The generator is written in C++, and two features choose how it runs. With `native`, this crate's
//! build script compiles it, which needs a C++17 compiler. With `wasm`, it runs as an embedded
//! WebAssembly module in the `wasmi` interpreter, which needs no compiler. Both produce the same
//! output.
//!
//! Both features are on by default. The native generator is used when it builds, and the wasm one
//! otherwise, which [`Config::compile`] then warns about. If you have a C++ compiler,
//! `default-features = false, features = ["native"]` avoids building the interpreter. To use the wasm
//! generator on purpose, without the warning, enable only `wasm`.
//!
//! Cargo builds build-time code without optimization, so the interpreter is slow by default. It takes
//! seconds for a small schema and minutes for a very large one. If you use the wasm generator,
//! optimize build-time code in your workspace:
//!
//! ```toml
//! [profile.dev.build-override]
//! opt-level = 3
//! [profile.release.build-override]
//! opt-level = 3
//! ```
//!
//! [`rapidproto`]: https://docs.rs/rapidproto/latest/rapidproto/
//! [`example`]: https://docs.rs/rapidproto/latest/rapidproto/example/index.html
//! [stream decoders]: Config::stream
//! [decode profile]: Config::field_modes
//! [`serde::Serialize`]: Config::serde
#![warn(missing_docs)]

use std::collections::btree_map::Entry;
use std::collections::{BTreeMap, BTreeSet};
use std::env;
use std::path::{Component, Path, PathBuf};
use std::sync::{Mutex, PoisonError};

/// Why this build uses the wasm generator although the `native` feature is on: the reason the
/// native one did not build. `None` when it built, or was not asked for.
#[doc(hidden)]
pub const NATIVE_FALLBACK: Option<&str> = option_env!("RAPIDPROTO_BUILD_FALLBACK");

/// One in-memory source file: `name` is how an `import` refers to it (e.g. `"types.proto"`), and
/// `body` is its text.
#[doc(hidden)]
pub struct SourceFile {
    /// How an `import` statement spells this file (e.g. `"types.proto"`).
    pub name: String,
    /// The file's `.proto` text.
    pub body: String,
}

/// The inputs for one generation: the entry files (the roots of the import closure, each named the
/// way an `import` would spell it), the sources those entries and their imports may pull in (a
/// superset is fine — only what the closure reaches is used), and the generation options.
#[doc(hidden)]
pub struct Request {
    /// The entry `.proto`s, named as an `import` would spell them.
    pub entries: Vec<String>,
    /// The entries and every file they may import (a superset is fine).
    pub sources: Vec<SourceFile>,
    /// A decode profile — the text of a `.modes` file (`drop` / `raw` / `unknown-fields` lines) — or
    /// empty for the default (decode every field).
    pub modes: String,
    /// Reserve space to track unknown fields on every message (see [`Config::unknown_present`]).
    pub unknown_present: bool,
    /// Emit the random-access `arena` decoder model (default on; see [`Config::arena`]).
    pub arena: bool,
    /// Emit the `stream` visitor model (default off; see [`Config::stream`]).
    pub stream: bool,
    /// Implement `serde::Serialize` (default off; see [`Config::serde`]).
    pub serde: bool,
    /// Where the generated file is included (see [`Config::new`]).
    pub module_path: String,
}

impl Default for Request {
    /// No entries or sources, no decode profile, the `arena` model only, included at the crate root.
    fn default() -> Self {
        Request {
            entries: Vec::new(),
            sources: Vec::new(),
            modes: String::new(),
            unknown_present: false,
            arena: true,
            stream: false,
            serde: false,
            module_path: "crate".to_owned(),
        }
    }
}

/// An error from the generator.
#[derive(Debug)]
pub struct GenError {
    /// The generator's status: 2 for a malformed request, 3 for a schema that does not resolve, 4 for
    /// a bad decode profile; negative for an I/O or internal failure. The tests and the CLI read it.
    #[doc(hidden)]
    pub code: i32,
    /// A description of the failure.
    pub message: String,
}

impl std::fmt::Display for GenError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "generator failed (status {}): {}",
            self.code, self.message
        )
    }
}

impl std::error::Error for GenError {}

/// Encodes a [`Request`] into the byte frame the generator takes, through either backend: a `RPWF5`
/// magic, then little-endian-u32-counted entry names, u32-counted `{name, body}` sources, the
/// `.modes` text, a one-byte unknown-present flag, two one-byte model flags (arena, stream), a one-byte
/// serde flag, and the module path. Bodies are length-prefixed, so a proto's newlines/quotes need no
/// escaping. The generator validates the options; the decode side is `rapidproto/rustgen/frame.hpp`
/// in the repository.
mod frame {
    use super::{GenError, Request};

    /// Write a u32 little-endian count/length, rejecting (never truncating) a value past u32::MAX --
    /// so a pathologically large source can't silently wrap its length prefix and corrupt the frame.
    fn put_len(buf: &mut Vec<u8>, n: usize) -> Result<(), GenError> {
        let len = u32::try_from(n).map_err(|_| GenError {
            code: -1,
            message: format!("frame field too large: {n} bytes (max {})", u32::MAX),
        })?;
        buf.extend_from_slice(&len.to_le_bytes());
        Ok(())
    }

    fn put_bytes(buf: &mut Vec<u8>, bytes: &[u8]) -> Result<(), GenError> {
        put_len(buf, bytes.len())?;
        buf.extend_from_slice(bytes);
        Ok(())
    }

    pub(super) fn encode(request: &Request) -> Result<Vec<u8>, GenError> {
        let mut buf = Vec::new();
        buf.extend_from_slice(b"RPWF5\n");
        put_len(&mut buf, request.entries.len())?;
        for entry in &request.entries {
            put_bytes(&mut buf, entry.as_bytes())?;
        }
        put_len(&mut buf, request.sources.len())?;
        for source in &request.sources {
            put_bytes(&mut buf, source.name.as_bytes())?;
            put_bytes(&mut buf, source.body.as_bytes())?;
        }
        put_bytes(&mut buf, request.modes.as_bytes())?;
        buf.push(u8::from(request.unknown_present));
        buf.push(u8::from(request.arena));
        buf.push(u8::from(request.stream));
        buf.push(u8::from(request.serde));
        put_bytes(&mut buf, request.module_path.as_bytes())?;
        Ok(buf)
    }
}

/// A way to run the generator (see [How the generator runs](crate#how-the-generator-runs)).
#[doc(hidden)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Backend {
    #[cfg(rp_native)]
    Native,
    #[cfg(feature = "wasm")]
    Wasm,
}

/// The backends this build has, the one [`Config`] uses first.
#[doc(hidden)]
pub const BACKENDS: &[Backend] = &[
    #[cfg(rp_native)]
    Backend::Native,
    #[cfg(feature = "wasm")]
    Backend::Wasm,
];

/// Run the generator on `request` through a given backend. Public for checking that the backends agree.
#[doc(hidden)]
pub fn generate_with(backend: Backend, request: &Request) -> Result<String, GenError> {
    let frame = frame::encode(request)?;
    let (status, text) = match backend {
        #[cfg(rp_native)]
        Backend::Native => native::run(&frame)?,
        #[cfg(feature = "wasm")]
        Backend::Wasm => wasm::run(frame)?,
    };
    if status == 0 {
        Ok(String::from_utf8_lossy(&text).into_owned())
    } else {
        Err(GenError {
            code: status,
            message: String::from_utf8_lossy(&text).trim_end().to_owned(),
        })
    }
}

/// The generator compiled by the build script, called in-process through its C ABI
/// (src/rustgen/native_entry.cpp in the repository).
#[cfg(rp_native)]
mod native {
    use std::ffi::{c_char, c_int, c_void};

    use super::{internal, GenError};

    type Sink = extern "C" fn(context: *mut c_void, data: *const c_char, len: usize);

    extern "C" {
        fn rapidproto_rustgen_run(
            frame: *const c_char,
            frame_len: usize,
            sink: Sink,
            context: *mut c_void,
        ) -> c_int;
    }

    // The stack the generator gets, as much as the wasm module links with: room for the parser's and
    // resolver's depth-capped recursion on a deep schema, whatever thread the caller is on.
    const STACK_BYTES: usize = 8 << 20;

    /// The generator's status and its output (the generated Rust, or the error message).
    pub(super) fn run(frame: &[u8]) -> Result<(i32, Vec<u8>), GenError> {
        std::thread::scope(|scope| {
            std::thread::Builder::new()
                .stack_size(STACK_BYTES)
                .spawn_scoped(scope, || call(frame))
                .map_err(internal)?
                .join()
                .map_err(|_| internal("the native generator panicked"))
        })
    }

    fn call(frame: &[u8]) -> (i32, Vec<u8>) {
        // Copies the output the generator hands over; `context` is the `Vec` below.
        extern "C" fn sink(context: *mut c_void, data: *const c_char, len: usize) {
            // SAFETY: `context` is the `&mut Vec<u8>` passed to the call, alive and unaliased for its
            // duration; `data` is valid for `len` bytes during this callback.
            unsafe {
                let out = &mut *context.cast::<Vec<u8>>();
                out.extend_from_slice(std::slice::from_raw_parts(data.cast::<u8>(), len));
            }
        }
        let mut text = Vec::new();
        // SAFETY: `frame` is valid for `frame.len()` bytes, and `sink` and `context` fit each other;
        // the generator calls `sink` once, before returning, and lets no exception escape.
        let status = unsafe {
            rapidproto_rustgen_run(
                frame.as_ptr().cast(),
                frame.len(),
                sink,
                std::ptr::from_mut(&mut text).cast(),
            )
        };
        if status == -1 {
            let detail = String::from_utf8_lossy(&text);
            text = format!("internal error in the native generator: {detail}").into_bytes();
        }
        (status, text)
    }
}

/// The embedded wasm generator in the wasmi interpreter: the frame as stdin, the output on stdout or
/// stderr, the status as the exit code.
#[cfg(feature = "wasm")]
mod wasm {
    use std::io::Cursor;
    use std::sync::OnceLock;

    use wasmi::{Engine, Linker, Module, Store};
    use wasmi_wasi::sync::WasiCtxBuilder;
    use wasmi_wasi::wasi_common::pipe::{ReadPipe, WritePipe};
    use wasmi_wasi::WasiCtx;

    use super::{internal, GenError};

    /// The embedded generator. Rebuilt by `wasm/build-wasm.sh` and byte-checked in CI, so it stays
    /// in sync with the generator source.
    const RUSTGEN_WASM: &[u8] = include_bytes!("../wasm/rustgen.wasm");

    /// The generator's status and its output (the generated Rust, or the error message).
    pub(super) fn run(frame: Vec<u8>) -> Result<(i32, Vec<u8>), GenError> {
        // Validating the embedded generator is the one expensive step, and it never changes, so
        // compile it once and reuse it: a caller that generates many files pays that cost once, not
        // per file. Only the lightweight Store/instance is per-call.
        let (engine, module) = compiled();

        // In-memory stdio: feed the frame as stdin, capture stdout/stderr. The pipes are cloneable
        // handles over a shared buffer; the WasiCtx holds one clone, we keep one to read afterwards.
        let stdout = WritePipe::new_in_memory();
        let stderr = WritePipe::new_in_memory();
        let wasi = WasiCtxBuilder::new()
            .stdin(Box::new(ReadPipe::from(frame)))
            .stdout(Box::new(stdout.clone()))
            .stderr(Box::new(stderr.clone()))
            .build();

        let mut store = Store::new(engine, wasi);
        let mut linker: Linker<WasiCtx> = Linker::new(engine);
        wasmi_wasi::sync::add_to_linker(&mut linker, |ctx| ctx).map_err(internal)?;

        let instance = linker
            .instantiate_and_start(&mut store, module)
            .map_err(internal)?;
        let start = instance
            .get_typed_func::<(), ()>(&store, "_start")
            .map_err(internal)?;
        let run = start.call(&mut store, ());

        // Drop the store so its clone of the pipe buffers is released; then we are the sole owner
        // and can take the captured bytes out.
        drop(store);
        let exit = match run {
            Ok(()) => 0,
            // A WASI `proc_exit(n)` surfaces as this; anything else is a real trap, not a clean exit.
            Err(error) => match error.i32_exit_status() {
                Some(code) => code,
                None => return Err(internal(error)),
            },
        };
        Ok((exit, take(if exit == 0 { stdout } else { stderr })))
    }

    /// The embedded generator, compiled once and reused across calls. It is a fixed, build-time
    /// asset, so a compile failure here means a broken build, not a runtime condition -- hence the
    /// panic.
    fn compiled() -> &'static (Engine, Module) {
        static CELL: OnceLock<(Engine, Module)> = OnceLock::new();
        CELL.get_or_init(|| {
            let engine = Engine::default();
            let module = Module::new(&engine, RUSTGEN_WASM)
                .expect("the embedded generator is a valid module");
            (engine, module)
        })
    }

    /// Take the bytes a finished in-memory pipe captured (sole owner by now).
    fn take(pipe: WritePipe<Cursor<Vec<u8>>>) -> Vec<u8> {
        pipe.try_into_inner()
            .expect("pipe still shared after the store was dropped")
            .into_inner()
    }
}

/// A failure inside the runtime (not a clean generator error): no exit code, so report it as -1.
fn internal(error: impl std::fmt::Display) -> GenError {
    GenError {
        code: -1,
        message: error.to_string(),
    }
}

/// Options for generating decoders.
///
/// The [crate docs](crate) show how to use it in `build.rs`.
#[derive(Debug)]
pub struct Config {
    module_path: String,
    includes: Vec<PathBuf>,
    modes: String,
    unknown_present: bool,
    arena: bool,
    stream: bool,
    serde: bool,
    backend: Backend,
}

impl Config {
    /// Creates a config for code included at `module_path`.
    ///
    /// The config generates arena decoders with no decode profile, and resolves imports in the current
    /// directory, which is the package root in a build script.
    ///
    /// `module_path` is `crate` for the crate root, or a path from it such as `crate::schema`. Its
    /// segments are ASCII identifiers. Write a keyword as a raw identifier, such as `r#type`.
    ///
    /// The generated code names its own types through this path, so it must lead to where you
    /// `include!` the file. A wrong path fails to compile.
    ///
    /// Include a file once per crate, and not inside a function. A doctest counts as a function unless
    /// it declares `fn main`. Each generated file needs its own path, so two files in one crate need
    /// two `Config`s. A lib, a bin and each file in `tests/` are separate crates, so each can include
    /// the same file at the same path.
    pub fn new(module_path: impl Into<String>) -> Self {
        Config {
            module_path: module_path.into(),
            includes: Vec::new(),
            modes: String::new(),
            unknown_present: false,
            arena: true,
            stream: false,
            serde: false,
            backend: BACKENDS[0],
        }
    }

    /// Adds a directory to search for `.proto` files.
    ///
    /// Once you add one, the current directory is no longer searched. If several directories have the
    /// same file, the first one added wins.
    pub fn include(mut self, dir: impl Into<PathBuf>) -> Self {
        self.includes.push(dir.into());
        self
    }

    /// Sets a decode profile, which changes what the arena decoders store.
    ///
    /// `modes` holds one directive per line, and `#` starts a comment:
    ///
    /// - `drop pkg.Msg.field` removes the field and its accessor.
    /// - `raw pkg.Msg.field` keeps a message or group field as its encoded message. The accessor
    ///   returns it as [`ProtoBytes`], in an `Option` for a singular field and in a slice for a
    ///   `repeated` one, ready for the field type's `decode`.
    /// - `unknown-fields pkg.Msg` adds `has_unknown_fields()` to the message.
    ///
    /// `drop` and `raw` also take a message type, `pkg.Msg`, to cover every field of that type, and
    /// `drop` takes an enum type the same way. A directive for a field wins over one for its type.
    /// Neither applies to a `oneof` member, `raw` does not apply to a `map` field, and `drop` does
    /// not apply to a `required` field. Naming such a field fails, and a directive for its type
    /// leaves it as it is. Stream decoders ignore the profile.
    ///
    /// ```no_run
    /// // build.rs
    /// rapidproto_build::Config::new("crate::schema")
    ///     .field_modes("drop shop.Order.notes\nraw shop.Order.items")
    ///     .compile(&["shop.proto"])
    ///     .expect("generate decoders");
    /// ```
    ///
    /// [`ProtoBytes`]: https://docs.rs/rapidproto/latest/rapidproto/struct.ProtoBytes.html
    pub fn field_modes(mut self, modes: impl Into<String>) -> Self {
        self.modes = modes.into();
        self
    }

    /// Adds `has_unknown_fields()` to every arena message.
    ///
    /// It returns `true` if the encoded message had a field the schema does not declare. Unknown
    /// fields inside a sub-message do not count.
    pub fn unknown_present(mut self, yes: bool) -> Self {
        self.unknown_present = yes;
        self
    }

    /// Generates arena decoders, which decode the whole message into an [`Arena`].
    ///
    /// They are on by default. At least one of `arena` and [`stream`](Config::stream) must be on.
    ///
    /// [`Arena`]: https://docs.rs/rapidproto/latest/rapidproto/struct.Arena.html
    pub fn arena(mut self, yes: bool) -> Self {
        self.arena = yes;
        self
    }

    /// Generates stream decoders, which pass the fields you select to your handlers.
    ///
    /// They are off by default. The [`rapidproto::stream`] docs show how to use them.
    ///
    /// Each message gets a `msg_stream!` macro, which builds a visitor from your handlers. The macro
    /// expands where you call it and reaches the rest of the generated code through the path given to
    /// [`Config::new`], so each module on that path must be visible from the call. Make the
    /// modules `pub` to call it from `tests/` or another crate. To call it from elsewhere in the
    /// crate, a module nested below the crate root needs `pub(crate)`.
    ///
    /// A `proc-macro` crate cannot export macros, so stream decoders do not compile there. Put the
    /// generated code in a separate crate instead.
    ///
    /// [`rapidproto::stream`]: https://docs.rs/rapidproto/latest/rapidproto/stream/index.html
    pub fn stream(mut self, yes: bool) -> Self {
        self.stream = yes;
        self
    }

    /// Implements `serde::Serialize` for the arena messages and the types generated for the schema's
    /// enums.
    ///
    /// It is off by default. When it is on, the generated code needs the `serde` feature of
    /// `rapidproto`, and does not compile without it. The [`rapidproto` docs] describe the output.
    ///
    /// To make this optional in your own crate, declare a `serde` feature that enables
    /// `rapidproto/serde`, and read it in `build.rs`:
    ///
    /// ```no_run
    /// // build.rs
    /// rapidproto_build::Config::new("crate::schema")
    ///     .serde(std::env::var_os("CARGO_FEATURE_SERDE").is_some())
    ///     .compile(&["message.proto"])
    ///     .expect("generate decoders");
    /// ```
    ///
    /// [`rapidproto` docs]: https://docs.rs/rapidproto/latest/rapidproto/#serde
    pub fn serde(mut self, yes: bool) -> Self {
        self.serde = yes;
        self
    }

    /// Generate through `backend` instead of the default one -- for checking that the backends agree.
    #[doc(hidden)]
    pub fn backend(mut self, backend: Backend) -> Self {
        self.backend = backend;
        self
    }

    /// Generates decoders for `entries` and everything they import, and returns the code.
    ///
    /// Imports resolve against every `.proto` file under the include directories. An entry is named by
    /// its path relative to the first include directory that holds it, or by its file name if none
    /// does. [`Config::compile`] also writes the file and tells cargo when to re-run the build script.
    pub fn generate(&self, entries: &[impl AsRef<Path>]) -> Result<String, GenError> {
        // Canonicalize the include dirs once, so the source walk and the entry-key derivation compare
        // paths in the same absolute/normalized/symlink-resolved terms. Without this a `./`-prefixed
        // or relative-vs-absolute entry path would key differently from how an import names the same
        // file, splitting the closure into two entries.
        let includes: Vec<PathBuf> = self
            .include_dirs()
            .iter()
            .map(|dir| {
                dir.canonicalize()
                    .map_err(|e| internal(format!("include dir {}: {e}", dir.display())))
            })
            .collect::<Result<_, _>>()?;

        let mut sources: BTreeMap<String, String> = BTreeMap::new();
        for include in &includes {
            collect_protos(include, include, &mut sources).map_err(internal)?;
        }
        let mut entry_names = Vec::with_capacity(entries.len());
        for entry in entries {
            let entry = entry.as_ref();
            let canonical = entry
                .canonicalize()
                .map_err(|e| internal(format!("entry {}: {e}", entry.display())))?;
            let name = import_relative_name(&canonical, &includes);
            let body = read(&canonical).map_err(internal)?;
            sources.insert(name.clone(), body);
            entry_names.push(name);
        }
        let request = Request {
            entries: entry_names,
            sources: sources
                .into_iter()
                .map(|(name, body)| SourceFile { name, body })
                .collect(),
            modes: self.modes.clone(),
            unknown_present: self.unknown_present,
            arena: self.arena,
            stream: self.stream,
            serde: self.serde,
            module_path: self.module_path.clone(),
        };
        generate_with(self.backend, &request)
    }

    /// Generates decoders for `entries` and everything they import, writes them to `OUT_DIR`, and
    /// returns the file's path.
    ///
    /// The file is named after the first entry, so `proto/message.proto` gives `message.rs`. A second
    /// call whose first entry has the same name, such as `other/message.proto`, fails. Use
    /// [`Config::generate`] to write such files under names of your own.
    ///
    /// Cargo re-runs the build script when an entry or a `.proto` file under the include directories
    /// changes.
    pub fn compile(&self, entries: &[impl AsRef<Path>]) -> Result<PathBuf, GenError> {
        // Warned from here, the consumer's own build script, because cargo hides the warnings of a
        // dependency's build script.
        if let Some(reason) = NATIVE_FALLBACK {
            static WARNED: std::sync::Once = std::sync::Once::new();
            WARNED.call_once(|| {
                println!(
                    "cargo:warning=rapidproto-build uses the slower wasm generator: the native one \
                     did not build, {reason}. To use the wasm one on purpose, depend on \
                     rapidproto-build with `default-features = false, features = [\"wasm\"]`."
                );
            });
        }
        let out_dir = env::var_os("OUT_DIR").ok_or_else(|| GenError {
            code: -1,
            message: "compile(): OUT_DIR is unset -- call it from a cargo build script".to_owned(),
        })?;
        // One file covers the whole closure; name it after the first entry's stem, so several
        // compile() calls in one build script land in distinct files.
        let stem = entries
            .first()
            .and_then(|e| e.as_ref().file_stem())
            .map_or_else(|| "schema".to_owned(), |s| s.to_string_lossy().into_owned());
        let out_path = PathBuf::from(out_dir).join(format!("{stem}.rs"));
        // A build script runs once per process, so this remembers the files of this build only.
        // Checked before generating, so a clash fails fast.
        static WRITTEN: Mutex<BTreeSet<PathBuf>> = Mutex::new(BTreeSet::new());
        let first = WRITTEN
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .insert(out_path.clone());
        if !first {
            return Err(GenError {
                code: -1,
                message: format!(
                    "compile(): an earlier call in this build script also writes {stem}.rs, \
                     since each call names its file after its first entry. Use generate() and \
                     write the files under names of your own"
                ),
            });
        }
        let code = self.generate(entries)?;
        std::fs::write(&out_path, code).map_err(|e| GenError {
            code: -1,
            message: format!("compile(): cannot write {}: {e}", out_path.display()),
        })?;

        // Rebuild tracking: the entries themselves, plus every proto on the include path. Watching the
        // whole include path (not just the resolved closure, which the generator does not report) is
        // deliberately broad: a build never goes stale, at the cost of an occasional rebuild when an
        // unrelated proto on the path changes.
        for entry in entries {
            println!("cargo:rerun-if-changed={}", entry.as_ref().display());
        }
        for dir in &self.include_dirs() {
            track_protos(dir);
        }
        Ok(out_path)
    }

    /// The include path: the added directories, or the cwd (the crate root in a build script) when
    /// none was added.
    fn include_dirs(&self) -> Vec<PathBuf> {
        if self.includes.is_empty() {
            vec![PathBuf::from(".")]
        } else {
            self.includes.clone()
        }
    }
}

/// Emit `cargo:rerun-if-changed` for every `.proto` under `dir` (recursively). An unreadable dir is
/// skipped silently -- it just means nothing there is tracked, and a real missing include surfaces as
/// a generation error, not here.
fn track_protos(dir: &Path) {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return;
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if path.is_dir() {
            track_protos(&path);
        } else if path.extension().is_some_and(|e| e == "proto") {
            println!("cargo:rerun-if-changed={}", path.display());
        }
    }
}

/// The name an `import` would use for `entry`: its path relative to the first `includes` directory
/// that contains it, otherwise its file name. `entry` and `includes` must already be canonicalized
/// (see [`Config::generate`]) so the prefix comparison is done in matching terms.
fn import_relative_name(entry: &Path, includes: &[PathBuf]) -> String {
    for include in includes {
        if let Ok(rel) = entry.strip_prefix(include) {
            return to_slash(rel);
        }
    }
    entry
        .file_name()
        .map(|n| n.to_string_lossy().into_owned())
        .unwrap_or_default()
}

/// Recursively add every `.proto` under `dir`, keyed by its path relative to `root` (the include
/// dir), in forward-slash form so the key matches an `import` string on any platform. Only `dir`
/// itself must be readable: below it, a directory or file that cannot be read (or is not UTF-8) is
/// skipped -- over-inclusion is harmless, and an import that needed it still fails as a missing
/// import. So pointing the include path at a large tree (the CLI's cwd default) cannot fail on an
/// unrelated file.
fn collect_protos(
    root: &Path,
    dir: &Path,
    out: &mut BTreeMap<String, String>,
) -> Result<(), String> {
    let entries = std::fs::read_dir(dir)
        .map_err(|e| format!("cannot read include dir {}: {e}", dir.display()))?;
    for entry in entries.flatten() {
        let path = entry.path();
        let Ok(file_type) = entry.file_type() else {
            continue;
        };
        if file_type.is_dir() {
            let _ = collect_protos(root, &path, out); // an unreadable subdirectory is skipped
        } else if path.extension().is_some_and(|e| e == "proto") {
            let rel = path.strip_prefix(root).unwrap_or(&path);
            // First include dir wins (like protoc): read and keep this file only if an earlier
            // include dir has not already provided the same key.
            if let Entry::Vacant(slot) = out.entry(to_slash(rel)) {
                if let Ok(body) = std::fs::read_to_string(&path) {
                    slot.insert(body);
                }
            }
        }
    }
    Ok(())
}

fn read(path: &Path) -> Result<String, String> {
    std::fs::read_to_string(path).map_err(|e| format!("cannot read {}: {e}", path.display()))
}

/// Forward-slash rendering of a relative path (import keys are `/`-separated regardless of OS).
fn to_slash(path: &Path) -> String {
    path.components()
        .filter_map(|c| match c {
            Component::Normal(s) => Some(s.to_string_lossy()),
            _ => None,
        })
        .collect::<Vec<_>>()
        .join("/")
}