1use std::collections::BTreeMap;
4use std::sync::LazyLock;
5
6use typst::diag::{At, FileError, FileResult, SourceResult};
7use typst::ecow::{EcoString, eco_format};
8use typst::engine::Engine;
9use typst::foundations::{
10 Array, Bytes, Capturer, Closure, ClosureNode, Dict, Func, Module, Scope, Scopes, Str, Value,
11 dict, func,
12};
13use typst::syntax::ast::{self, AstNode};
14use typst::syntax::package::PackageSpec;
15use typst::syntax::{FileId, RootedPath, Span, SyntaxNode, VirtualPath, VirtualRoot, parse_code};
16use typst::utils::LazyHash;
17use typst::{Feature, Library, LibraryExt, World};
18use typst_eval::CapturesVisitor;
19
20use crate::engine::route::ParamSet;
21
22pub const PROTOCOL_VERSION: i64 = 9;
24pub const ASTER_VERSION: &str = env!("CARGO_PKG_VERSION");
26pub const INPUT_NAME: &str = "_aster";
28
29pub struct Runtime {
31 inputs: Dict,
32 library: LazyHash<Library>,
33 page_routes: PageRoutes,
34}
35
36impl Runtime {
37 pub fn new(entries: impl IntoIterator<Item = ContentEntry>, dev: bool) -> Self {
39 let mut collections: BTreeMap<EcoString, Vec<(EcoString, RootedPath)>> = BTreeMap::new();
40 for entry in entries {
41 collections
42 .entry(entry.collection)
43 .or_default()
44 .push((entry.id, entry.source));
45 }
46
47 let mut inputs = Dict::new();
48 inputs.insert(Str::from(INPUT_NAME), protocol_value(collections, dev));
49 let library = library(&inputs);
50 Self {
51 inputs,
52 library,
53 page_routes: PageRoutes::default(),
54 }
55 }
56
57 pub fn with_page_routes(mut self, pages: Vec<EcoString>) -> Self {
59 self.page_routes = PageRoutes::new(pages);
60 self
61 }
62
63 pub fn with_site(mut self, pages: &[SitePage]) -> Self {
65 let pages = pages
66 .iter()
67 .map(|page| {
68 let content = page.content.as_ref().map_or(Value::None, |content| {
69 Value::Dict(dict! {
70 "html" => content.html.clone(),
71 "text" => content.text.clone(),
72 })
73 });
74 Value::Dict(dict! {
75 "path" => page.path.clone(),
76 "html" => page.html.clone(),
77 "content" => content,
78 })
79 })
80 .collect::<Array>();
81 let Value::Dict(mut protocol) = self
82 .inputs
83 .get(INPUT_NAME)
84 .expect("Aster inputs must contain the runtime protocol")
85 .clone()
86 else {
87 unreachable!("Aster runtime protocol must be a dictionary");
88 };
89 protocol.insert("site".into(), Value::Dict(dict! { "pages" => pages }));
90 self.inputs.insert(INPUT_NAME.into(), Value::Dict(protocol));
91 self.library = library(&self.inputs);
92 self
93 }
94
95 pub fn probe(&self) -> CompilationRuntime<'_> {
97 CompilationRuntime {
98 runtime: self,
99 route: RouteContext::default(),
100 }
101 }
102
103 pub fn for_route(&self, path: EcoString, params: &ParamSet) -> CompilationRuntime<'_> {
105 CompilationRuntime {
106 runtime: self,
107 route: RouteContext::new(path, params),
108 }
109 }
110}
111
112pub struct CompilationRuntime<'a> {
114 runtime: &'a Runtime,
115 route: RouteContext,
116}
117
118impl CompilationRuntime<'_> {
119 pub fn library(&self) -> &LazyHash<Library> {
120 &self.runtime.library
121 }
122
123 pub fn resolve_file(&self, id: FileId) -> Option<FileResult<Bytes>> {
125 if !owns_runtime_file(id) {
126 return None;
127 }
128
129 let value = self
130 .route
131 .value(id)
132 .or_else(|| self.runtime.page_routes.value(id));
133 Some(
134 value
135 .cloned()
136 .map(Str::from)
137 .map(Bytes::from_string)
138 .ok_or_else(|| FileError::NotFound(id.vpath().get_with_slash().into())),
139 )
140 }
141}
142
143#[derive(Default)]
144struct RouteContext {
145 path: Option<EcoString>,
146 params: ParamSet,
147}
148
149impl RouteContext {
150 fn new(path: EcoString, params: &ParamSet) -> Self {
151 Self {
152 path: Some(path),
153 params: params.clone(),
154 }
155 }
156
157 fn path_id() -> FileId {
158 runtime_file_id("route/path")
159 }
160
161 fn param_id(name: &str) -> FileId {
162 runtime_file_id(&format!("route/params/{}", hex::encode(name)))
163 }
164
165 fn value(&self, id: FileId) -> Option<&EcoString> {
166 if id == Self::path_id() {
167 return self.path.as_ref();
168 }
169
170 let encoded = id
171 .vpath()
172 .get_without_slash()
173 .strip_prefix("route/params/")?;
174 let name = hex::decode(encoded).ok()?;
175 self.params.get(std::str::from_utf8(&name).ok()?)
176 }
177}
178
179#[derive(Default)]
180struct PageRoutes(Vec<EcoString>);
181
182impl PageRoutes {
183 fn new(pages: Vec<EcoString>) -> Self {
184 Self(pages)
185 }
186
187 fn id(index: usize) -> FileId {
188 runtime_file_id(&format!("routes/pages/{index}"))
189 }
190
191 fn value(&self, id: FileId) -> Option<&EcoString> {
192 let index = id
193 .vpath()
194 .get_without_slash()
195 .strip_prefix("routes/pages/")?
196 .parse::<usize>()
197 .ok()?;
198 self.0.get(index)
199 }
200}
201
202fn owns_runtime_file(id: FileId) -> bool {
203 matches!(id.root(), VirtualRoot::Package(package) if package == runtime_package())
204}
205
206fn runtime_file_id(path: &str) -> FileId {
207 RootedPath::new(
208 VirtualRoot::Package(runtime_package().clone()),
209 VirtualPath::new(path).expect("Aster runtime path must be valid"),
210 )
211 .intern()
212}
213
214fn runtime_package() -> &'static PackageSpec {
215 static PACKAGE: LazyLock<PackageSpec> = LazyLock::new(|| {
216 "@aster/runtime:0.1.0"
217 .parse()
218 .expect("Aster runtime package specification must be valid")
219 });
220 &PACKAGE
221}
222
223fn library(inputs: &Dict) -> LazyHash<Library> {
224 LazyHash::new(
225 Library::builder()
226 .with_inputs(inputs.clone())
227 .with_features([Feature::Html].into_iter().collect())
228 .build(),
229 )
230}
231
232pub struct ContentEntry {
234 pub collection: EcoString,
236 pub id: EcoString,
238 pub source: RootedPath,
240}
241
242pub struct SitePage {
244 pub path: EcoString,
246 pub html: EcoString,
248 pub content: Option<SiteContent>,
250}
251
252pub struct SiteContent {
254 pub html: EcoString,
255 pub text: EcoString,
256}
257
258fn protocol_value(
259 collections: BTreeMap<EcoString, Vec<(EcoString, RootedPath)>>,
260 dev: bool,
261) -> Value {
262 let mut packed_collections = Dict::new();
263 for (collection_name, entries) in collections {
264 let mut packed_entries = Dict::new();
265 for (id, source) in entries {
266 packed_entries.insert(
267 Str::from(id.as_str()),
268 Value::Module(entry_module(&collection_name, &id, source)),
269 );
270 }
271 packed_collections.insert(
272 Str::from(collection_name.as_str()),
273 Value::Dict(packed_entries),
274 );
275 }
276
277 Value::Dict(dict! {
278 "protocol" => PROTOCOL_VERSION,
279 "version" => ASTER_VERSION,
280 "dev" => dev,
281 "collections" => packed_collections,
282 "route" => route_module(),
283 "routes" => routes_module(),
284 "site" => dict! { "pages" => Array::new() },
285 })
286}
287
288fn route_module() -> Module {
289 let mut scope = Scope::new();
290 scope.define_func::<path>();
291 scope.define_func::<param>();
292 Module::new("route", scope)
293}
294
295fn routes_module() -> Module {
296 let mut scope = Scope::new();
297 scope.define_func::<pages>();
298 Module::new("routes", scope)
299}
300
301fn read(engine: &mut Engine, id: FileId, span: Span) -> SourceResult<Option<Str>> {
302 match engine.world.file(id) {
303 Ok(bytes) => bytes.to_str().map(Some).map_err(FileError::from).at(span),
304 Err(FileError::NotFound(_)) => Ok(None),
305 Err(error) => Err(error).at(span),
306 }
307}
308
309fn route_value(
310 engine: &mut Engine,
311 id: FileId,
312 default: Option<Value>,
313 span: Span,
314) -> SourceResult<Value> {
315 Ok(read(engine, id, span)?
316 .map(Value::Str)
317 .unwrap_or_else(|| default.unwrap_or(Value::None)))
318}
319
320#[func]
322fn path(
323 engine: &mut Engine,
324 span: Span,
325 #[named]
327 default: Option<Value>,
328) -> SourceResult<Value> {
329 route_value(engine, RouteContext::path_id(), default, span)
330}
331
332#[func]
334fn param(
335 engine: &mut Engine,
336 span: Span,
337 name: Str,
339 #[named]
341 default: Option<Value>,
342) -> SourceResult<Value> {
343 route_value(engine, RouteContext::param_id(name.as_str()), default, span)
344}
345
346#[func]
348fn pages(engine: &mut Engine, span: Span) -> SourceResult<Array> {
349 let mut pages = Array::new();
350 for index in 0.. {
351 let Some(path) = read(engine, PageRoutes::id(index), span)? else {
352 break;
353 };
354 pages.push(Value::Str(path));
355 }
356 Ok(pages)
357}
358
359fn entry_module(collection: &EcoString, id: &EcoString, source: RootedPath) -> Module {
360 let mut scope = Scope::new();
361 scope.define("id", Str::from(id.as_str()));
362 scope.define("collection", Str::from(collection.as_str()));
363 scope.define("metadata", metadata_closure(source.clone()));
364 scope.define("render", render_closure(source));
365 Module::new(eco_format!("{collection}/{id}"), scope)
366}
367
368fn metadata_closure(source: RootedPath) -> Func {
369 const METADATA_CLOSURE_SOURCE: &str = r#"() => {
370 let find-frontmatter(node) = {
371 let fields = node.fields()
372 if fields.at("label", default: none) == <aster-frontmatter> {
373 let value = fields.at("value", default: (:))
374 return if type(value) == dictionary { value } else { (:) }
375 }
376
377 for value in fields.values() {
378 if type(value) == content {
379 let found = find-frontmatter(value)
380 if found != none { return found }
381 } else if type(value) == array {
382 for child in value {
383 if type(child) == content {
384 let found = find-frontmatter(child)
385 if found != none { return found }
386 }
387 }
388 }
389 }
390
391 none
392 }
393
394 import source as entry-module
395 let entry-content = include entry-module
396 let metadata = find-frontmatter(entry-content)
397 if metadata == none { (:) } else { metadata }
398}"#;
399
400 static METADATA_CLOSURE_NODE: LazyLock<SyntaxNode> =
401 LazyLock::new(|| parse_closure(METADATA_CLOSURE_SOURCE));
402
403 captured_closure(METADATA_CLOSURE_NODE.clone(), source)
404}
405
406fn render_closure(source: RootedPath) -> Func {
407 const RENDER_CLOSURE_SOURCE: &str = r#"() => {
408 import source as entry-module
409 include entry-module
410}"#;
411
412 static RENDER_CLOSURE_NODE: LazyLock<SyntaxNode> =
413 LazyLock::new(|| parse_closure(RENDER_CLOSURE_SOURCE));
414
415 captured_closure(RENDER_CLOSURE_NODE.clone(), source)
416}
417
418fn parse_closure(source: &str) -> SyntaxNode {
419 let root = parse_code(source);
420 let (errors, _) = root.errors_and_warnings();
421 assert!(errors.is_empty(), "Aster entry closure must parse");
422 let code = root
423 .cast::<ast::Code>()
424 .expect("entry closure must be code");
425 let mut expressions = code.exprs();
426 let ast::Expr::Closure(closure) = expressions.next().expect("entry closure must exist") else {
427 panic!("entry expression must be a closure");
428 };
429 assert!(
430 expressions.next().is_none(),
431 "entry closure must be the only expression"
432 );
433 closure.to_untyped().clone()
434}
435
436fn captured_closure(node: SyntaxNode, source: RootedPath) -> Func {
437 static CAPTURE_LIBRARY: LazyLock<Library> = LazyLock::new(Library::default);
438
439 let mut scopes = Scopes::new(Some(&CAPTURE_LIBRARY));
440 scopes.top.define("source", source);
441
442 let mut captures = CapturesVisitor::new(Some(&scopes), Capturer::Function);
443 captures.visit(&node);
444 Func::from(Closure {
445 node: ClosureNode::Closure(node),
446 defaults: Vec::new(),
447 captured: captures.finish(),
448 num_pos_params: 0,
449 })
450}
451
452#[cfg(test)]
453mod tests {
454 use super::*;
455 use typst::syntax::{VirtualPath, VirtualRoot};
456
457 fn empty() -> Runtime {
458 Runtime::new(std::iter::empty(), false)
459 }
460
461 #[test]
462 fn protocol_contains_lazy_entry_modules() {
463 let runtime = Runtime::new(
464 [ContentEntry {
465 collection: "blog".into(),
466 id: "nested/post".into(),
467 source: RootedPath::new(
468 VirtualRoot::Project,
469 VirtualPath::new("content/blog/nested/post.typ").unwrap(),
470 ),
471 }],
472 false,
473 );
474
475 let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
476 panic!("protocol must be a dictionary");
477 };
478 let Value::Dict(collections) = protocol.get("collections").unwrap() else {
479 panic!("collections must be a dictionary");
480 };
481 let Value::Dict(blog) = collections.get("blog").unwrap() else {
482 panic!("collection must be a dictionary");
483 };
484 let Value::Module(entry) = blog.get("nested/post").unwrap() else {
485 panic!("entry must be a module");
486 };
487 assert_eq!(
488 entry.field("id", ()).unwrap(),
489 &Value::Str(Str::from("nested/post"))
490 );
491 assert_eq!(
492 entry.field("collection", ()).unwrap(),
493 &Value::Str(Str::from("blog"))
494 );
495 assert!(matches!(
496 entry.field("metadata", ()).unwrap(),
497 Value::Func(_)
498 ));
499 assert!(matches!(entry.field("render", ()).unwrap(), Value::Func(_)));
500 assert!(entry.field("file-path", ()).is_err());
501 assert!(entry.field("content", ()).is_err());
502 }
503
504 #[test]
505 fn empty_protocol_has_one_owner() {
506 let runtime = empty();
507 let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
508 panic!("protocol must be a dictionary");
509 };
510 assert_eq!(
511 protocol.get("protocol").unwrap(),
512 &Value::Int(PROTOCOL_VERSION)
513 );
514 assert_eq!(
515 protocol.get("collections").unwrap(),
516 &Value::Dict(Dict::new())
517 );
518 assert_eq!(
519 protocol.get("version").unwrap(),
520 &Value::Str(Str::from(ASTER_VERSION))
521 );
522 assert_eq!(protocol.get("dev").unwrap(), &Value::Bool(false));
523 let Value::Module(route) = protocol.get("route").unwrap() else {
524 panic!("route protocol must be a module");
525 };
526 assert!(matches!(route.field("path", ()).unwrap(), Value::Func(_)));
527 assert!(matches!(route.field("param", ()).unwrap(), Value::Func(_)));
528 }
529
530 #[test]
531 fn protocol_exposes_development_mode() {
532 let runtime = Runtime::new(std::iter::empty(), true);
533 let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
534 panic!("protocol must be a dictionary");
535 };
536
537 assert_eq!(protocol.get("dev").unwrap(), &Value::Bool(true));
538 }
539
540 #[test]
541 fn compilation_runtime_resolves_virtual_files_without_changing_the_protocol() {
542 let base = empty();
543 let library = base.library.clone();
544 let base = base.with_page_routes(vec!["/".into(), "/blog/post/".into()]);
545 assert!(base.library == library);
546 let params = crate::engine::route::ParamSet::from([
547 ("site".into(), "route".into()),
548 (INPUT_NAME.into(), "nested".into()),
549 ("..".into(), "parent".into()),
550 ]);
551 let runtime = base.for_route("/blog/post/".into(), ¶ms);
552
553 assert_eq!(base.inputs.len(), 1);
554 let Value::Dict(protocol) = base.inputs.get(INPUT_NAME).unwrap() else {
555 panic!("runtime protocol must be a dictionary");
556 };
557 let Value::Module(route_module) = protocol.get("route").unwrap() else {
558 panic!("route protocol must be a module");
559 };
560 assert_eq!(
561 runtime
562 .resolve_file(RouteContext::path_id())
563 .unwrap()
564 .unwrap()
565 .to_str()
566 .unwrap(),
567 Str::from("/blog/post/")
568 );
569 assert_eq!(
570 runtime
571 .resolve_file(RouteContext::param_id("site"))
572 .unwrap()
573 .unwrap()
574 .to_str()
575 .unwrap(),
576 Str::from("route")
577 );
578 assert_eq!(
579 runtime
580 .resolve_file(RouteContext::param_id(INPUT_NAME))
581 .unwrap()
582 .unwrap()
583 .to_str()
584 .unwrap(),
585 Str::from("nested")
586 );
587 assert_eq!(
588 runtime
589 .resolve_file(RouteContext::param_id(".."))
590 .unwrap()
591 .unwrap()
592 .to_str()
593 .unwrap(),
594 Str::from("parent")
595 );
596 assert!(
597 runtime
598 .resolve_file(RouteContext::param_id("missing"))
599 .unwrap()
600 .is_err()
601 );
602 assert!(matches!(
603 route_module.field("path", ()).unwrap(),
604 Value::Func(_)
605 ));
606 let Value::Module(routes) = protocol.get("routes").unwrap() else {
607 panic!("planned routes must be a module");
608 };
609 assert!(matches!(routes.field("pages", ()).unwrap(), Value::Func(_)));
610 assert_eq!(
611 runtime
612 .resolve_file(PageRoutes::id(0))
613 .unwrap()
614 .unwrap()
615 .to_str()
616 .unwrap(),
617 Str::from("/")
618 );
619 assert_eq!(
620 runtime
621 .resolve_file(PageRoutes::id(1))
622 .unwrap()
623 .unwrap()
624 .to_str()
625 .unwrap(),
626 Str::from("/blog/post/")
627 );
628 assert!(runtime.resolve_file(PageRoutes::id(2)).unwrap().is_err());
629 assert!(routes.field("endpoints", ()).is_err());
630 }
631
632 #[test]
633 fn site_snapshot_exposes_final_page_content() {
634 let runtime = empty().with_site(&[SitePage {
635 path: "/post/".into(),
636 html: "<html>...</html>".into(),
637 content: Some(SiteContent {
638 html: "<article>Post</article>".into(),
639 text: "Post".into(),
640 }),
641 }]);
642 let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
643 panic!("runtime protocol must be a dictionary");
644 };
645 let Value::Dict(site) = protocol.get("site").unwrap() else {
646 panic!("site snapshot must be a dictionary");
647 };
648 let Value::Array(pages) = site.get("pages").unwrap() else {
649 panic!("site pages must be an array");
650 };
651 assert_eq!(pages.len(), 1);
652 }
653}