cml/types/
expose.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::types::common::*;
6use crate::types::right::{Rights, RightsClause};
7use crate::{
8    AnyRef, AsClause, AsClauseContext, Canonicalize, CapabilityClause, DictionaryRef, Error,
9    EventScope, FilterClause, FromClause, FromClauseContext, PathClause, SourceAvailability,
10};
11
12use crate::one_or_many::{
13    OneOrMany, one_or_many_from_context, one_or_many_from_impl, option_one_or_many_as_ref,
14};
15pub use cm_types::{
16    Availability, BorrowedName, BoundedName, DependencyType, HandleType, Name, OnTerminate,
17    ParseError, Path, RelativePath, StartupMode, Url,
18};
19use cml_macro::{OneOrMany, Reference};
20use json_spanned_value::Spanned;
21use reference_doc::ReferenceDoc;
22use serde::{Deserialize, Serialize};
23use serde_json::{Map, Value};
24
25use std::fmt;
26use std::path::PathBuf;
27use std::sync::Arc;
28
29/// Example:
30///
31/// ```json5
32/// expose: [
33///     {
34///         directory: "themes",
35///         from: "self",
36///     },
37///     {
38///         protocol: "pkg.Cache",
39///         from: "#pkg_cache",
40///         as: "fuchsia.pkg.PackageCache",
41///     },
42///     {
43///         protocol: [
44///             "fuchsia.ui.app.ViewProvider",
45///             "fuchsia.fonts.Provider",
46///         ],
47///         from: "self",
48///     },
49///     {
50///         runner: "web-chromium",
51///         from: "#web_runner",
52///         as: "web",
53///     },
54///     {
55///         resolver: "full-resolver",
56///         from: "#full-resolver",
57///     },
58/// ],
59/// ```
60#[derive(Deserialize, Debug, PartialEq, Clone, ReferenceDoc, Serialize)]
61#[serde(deny_unknown_fields)]
62#[reference_doc(fields_as = "list", top_level_doc_after_fields)]
63pub struct Expose {
64    /// When routing a service, the [name](#name) of a [service capability][doc-service].
65    #[serde(skip_serializing_if = "Option::is_none")]
66    #[reference_doc(skip = true)]
67    pub service: Option<OneOrMany<Name>>,
68
69    /// When routing a protocol, the [name](#name) of a [protocol capability][doc-protocol].
70    #[serde(skip_serializing_if = "Option::is_none")]
71    #[reference_doc(skip = true)]
72    pub protocol: Option<OneOrMany<Name>>,
73
74    /// When routing a directory, the [name](#name) of a [directory capability][doc-directory].
75    #[serde(skip_serializing_if = "Option::is_none")]
76    #[reference_doc(skip = true)]
77    pub directory: Option<OneOrMany<Name>>,
78
79    /// When routing a runner, the [name](#name) of a [runner capability][doc-runners].
80    #[serde(skip_serializing_if = "Option::is_none")]
81    #[reference_doc(skip = true)]
82    pub runner: Option<OneOrMany<Name>>,
83
84    /// When routing a resolver, the [name](#name) of a [resolver capability][doc-resolvers].
85    #[serde(skip_serializing_if = "Option::is_none")]
86    #[reference_doc(skip = true)]
87    pub resolver: Option<OneOrMany<Name>>,
88
89    /// When routing a dictionary, the [name](#name) of a [dictionary capability][doc-dictionaries].
90    #[serde(skip_serializing_if = "Option::is_none")]
91    #[reference_doc(skip = true)]
92    pub dictionary: Option<OneOrMany<Name>>,
93
94    /// When routing a config, the [name](#name) of a configuration capability.
95    #[serde(skip_serializing_if = "Option::is_none")]
96    #[reference_doc(skip = true)]
97    pub config: Option<OneOrMany<Name>>,
98
99    /// `from`: The source of the capability, one of:
100    /// - `self`: This component. Requires a corresponding
101    ///     [`capability`](#capabilities) declaration.
102    /// - `framework`: The Component Framework runtime.
103    /// - `#<child-name>`: A [reference](#references) to a child component
104    ///     instance.
105    pub from: OneOrMany<ExposeFromRef>,
106
107    /// The [name](#name) for the capability as it will be known by the target. If omitted,
108    /// defaults to the original name. `as` cannot be used when an array of multiple capability
109    /// names is provided.
110    #[serde(skip_serializing_if = "Option::is_none")]
111    pub r#as: Option<Name>,
112
113    /// The capability target. Either `parent` or `framework`. Defaults to `parent`.
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub to: Option<ExposeToRef>,
116
117    /// (`directory` only) the maximum [directory rights][doc-directory-rights] to apply to
118    /// the exposed directory capability.
119    #[serde(skip_serializing_if = "Option::is_none")]
120    #[reference_doc(json_type = "array of string")]
121    pub rights: Option<Rights>,
122
123    /// (`directory` only) the relative path of a subdirectory within the source directory
124    /// capability to route.
125    #[serde(skip_serializing_if = "Option::is_none")]
126    pub subdir: Option<RelativePath>,
127
128    /// (`event_stream` only) the name(s) of the event streams being exposed.
129    #[serde(skip_serializing_if = "Option::is_none")]
130    pub event_stream: Option<OneOrMany<Name>>,
131
132    /// (`event_stream` only) the scope(s) of the event streams being exposed. This is used to
133    /// downscope the range of components to which an event stream refers and make it refer only to
134    /// the components defined in the scope.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub scope: Option<OneOrMany<EventScope>>,
137
138    /// `availability` _(optional)_: The expectations around this capability's availability. Affects
139    /// build-time and runtime route validation. One of:
140    /// - `required` (default): a required dependency, the source must exist and provide it. Use
141    ///     this when the target of this expose requires this capability to function properly.
142    /// - `optional`: an optional dependency. Use this when the target of the expose can function
143    ///     with or without this capability. The target must not have a `required` dependency on the
144    ///     capability. The ultimate source of this expose must be `void` or an actual component.
145    /// - `same_as_target`: the availability expectations of this capability will match the
146    ///     target's. If the target requires the capability, then this field is set to `required`.
147    ///     If the target has an optional dependency on the capability, then the field is set to
148    ///     `optional`.
149    /// - `transitional`: like `optional`, but will tolerate a missing source. Use this
150    ///     only to avoid validation errors during transitional periods of multi-step code changes.
151    ///
152    /// For more information, see the
153    /// [availability](/docs/concepts/components/v2/capabilities/availability.md) documentation.
154    #[serde(skip_serializing_if = "Option::is_none")]
155    pub availability: Option<Availability>,
156
157    /// Whether or not the source of this offer must exist. One of:
158    /// - `required` (default): the source (`from`) must be defined in this manifest.
159    /// - `unknown`: the source of this offer will be rewritten to `void` if its source (`from`)
160    ///     is not defined in this manifest after includes are processed.
161    #[serde(skip_serializing_if = "Option::is_none")]
162    pub source_availability: Option<SourceAvailability>,
163}
164
165impl Expose {
166    pub fn new_from(from: OneOrMany<ExposeFromRef>) -> Self {
167        Self {
168            from,
169            service: None,
170            protocol: None,
171            directory: None,
172            config: None,
173            runner: None,
174            resolver: None,
175            dictionary: None,
176            r#as: None,
177            to: None,
178            rights: None,
179            subdir: None,
180            event_stream: None,
181            scope: None,
182            availability: None,
183            source_availability: None,
184        }
185    }
186}
187
188impl FromClause for Expose {
189    fn from_(&self) -> OneOrMany<AnyRef<'_>> {
190        one_or_many_from_impl(&self.from)
191    }
192}
193
194impl AsClause for Expose {
195    fn r#as(&self) -> Option<&BorrowedName> {
196        self.r#as.as_ref().map(Name::as_ref)
197    }
198}
199
200impl PathClause for Expose {
201    fn path(&self) -> Option<&Path> {
202        None
203    }
204}
205
206impl FilterClause for Expose {
207    fn filter(&self) -> Option<&Map<String, Value>> {
208        None
209    }
210}
211
212impl RightsClause for Expose {
213    fn rights(&self) -> Option<&Rights> {
214        self.rights.as_ref()
215    }
216}
217
218impl Canonicalize for Expose {
219    fn canonicalize(&mut self) {
220        // Sort the names of the capabilities. Only capabilities with OneOrMany values are included here.
221        if let Some(service) = &mut self.service {
222            service.canonicalize();
223        } else if let Some(protocol) = &mut self.protocol {
224            protocol.canonicalize();
225        } else if let Some(directory) = &mut self.directory {
226            directory.canonicalize();
227        } else if let Some(runner) = &mut self.runner {
228            runner.canonicalize();
229        } else if let Some(resolver) = &mut self.resolver {
230            resolver.canonicalize();
231        } else if let Some(event_stream) = &mut self.event_stream {
232            event_stream.canonicalize();
233            if let Some(scope) = &mut self.scope {
234                scope.canonicalize();
235            }
236        }
237        // TODO(https://fxbug.dev/300500098): canonicalize dictionaries
238    }
239}
240
241impl CapabilityClause for Expose {
242    fn service(&self) -> Option<OneOrMany<&BorrowedName>> {
243        option_one_or_many_as_ref(&self.service)
244    }
245    fn protocol(&self) -> Option<OneOrMany<&BorrowedName>> {
246        option_one_or_many_as_ref(&self.protocol)
247    }
248    fn directory(&self) -> Option<OneOrMany<&BorrowedName>> {
249        option_one_or_many_as_ref(&self.directory)
250    }
251    fn storage(&self) -> Option<OneOrMany<&BorrowedName>> {
252        None
253    }
254    fn runner(&self) -> Option<OneOrMany<&BorrowedName>> {
255        option_one_or_many_as_ref(&self.runner)
256    }
257    fn resolver(&self) -> Option<OneOrMany<&BorrowedName>> {
258        option_one_or_many_as_ref(&self.resolver)
259    }
260    fn event_stream(&self) -> Option<OneOrMany<&BorrowedName>> {
261        option_one_or_many_as_ref(&self.event_stream)
262    }
263    fn dictionary(&self) -> Option<OneOrMany<&BorrowedName>> {
264        option_one_or_many_as_ref(&self.dictionary)
265    }
266    fn config(&self) -> Option<OneOrMany<&BorrowedName>> {
267        option_one_or_many_as_ref(&self.config)
268    }
269
270    fn set_service(&mut self, o: Option<OneOrMany<Name>>) {
271        self.service = o;
272    }
273    fn set_protocol(&mut self, o: Option<OneOrMany<Name>>) {
274        self.protocol = o;
275    }
276    fn set_directory(&mut self, o: Option<OneOrMany<Name>>) {
277        self.directory = o;
278    }
279    fn set_storage(&mut self, _o: Option<OneOrMany<Name>>) {}
280    fn set_runner(&mut self, o: Option<OneOrMany<Name>>) {
281        self.runner = o;
282    }
283    fn set_resolver(&mut self, o: Option<OneOrMany<Name>>) {
284        self.resolver = o;
285    }
286    fn set_event_stream(&mut self, o: Option<OneOrMany<Name>>) {
287        self.event_stream = o;
288    }
289    fn set_dictionary(&mut self, o: Option<OneOrMany<Name>>) {
290        self.dictionary = o;
291    }
292    fn set_config(&mut self, o: Option<OneOrMany<Name>>) {
293        self.config = o;
294    }
295
296    fn availability(&self) -> Option<Availability> {
297        None
298    }
299    fn set_availability(&mut self, _a: Option<Availability>) {}
300
301    fn decl_type(&self) -> &'static str {
302        "expose"
303    }
304    fn supported(&self) -> &[&'static str] {
305        &[
306            "service",
307            "protocol",
308            "directory",
309            "runner",
310            "resolver",
311            "event_stream",
312            "dictionary",
313            "config",
314        ]
315    }
316    fn are_many_names_allowed(&self) -> bool {
317        [
318            "service",
319            "protocol",
320            "directory",
321            "runner",
322            "resolver",
323            "event_stream",
324            "dictionary",
325            "config",
326        ]
327        .contains(&self.capability_type().unwrap())
328    }
329}
330
331/// Generates deserializer for `OneOrMany<ExposeFromRef>`.
332#[derive(OneOrMany, Debug, Clone)]
333#[one_or_many(
334    expected = "one or an array of \"framework\", \"self\", \"#<child-name>\", or a dictionary path",
335    inner_type = "ExposeFromRef",
336    min_length = 1,
337    unique_items = true
338)]
339pub struct OneOrManyExposeFromRefs;
340
341/// A reference in an `expose from`.
342#[derive(Debug, PartialEq, Eq, Hash, Clone, Reference)]
343#[reference(expected = "\"framework\", \"self\", \"void\", or \"#<child-name>\"")]
344pub enum ExposeFromRef {
345    /// A reference to a child or collection.
346    Named(Name),
347    /// A reference to the framework.
348    Framework,
349    /// A reference to this component.
350    Self_,
351    /// An intentionally omitted source.
352    Void,
353    /// A reference to a dictionary.
354    Dictionary(DictionaryRef),
355}
356
357/// A reference in an `expose to`.
358#[derive(Debug, PartialEq, Eq, Hash, Clone, Reference)]
359#[reference(expected = "\"parent\", \"framework\", or none")]
360pub enum ExposeToRef {
361    /// A reference to the parent.
362    Parent,
363    /// A reference to the framework.
364    Framework,
365}
366
367#[derive(Deserialize, Debug, PartialEq, Clone)]
368#[serde(deny_unknown_fields)]
369pub struct ParsedExpose {
370    #[serde(default, skip_serializing_if = "Option::is_none")]
371    pub service: Option<Spanned<OneOrMany<Name>>>,
372    pub protocol: Option<Spanned<OneOrMany<Name>>>,
373    pub directory: Option<Spanned<OneOrMany<Name>>>,
374    pub runner: Option<Spanned<OneOrMany<Name>>>,
375    pub resolver: Option<Spanned<OneOrMany<Name>>>,
376    pub dictionary: Option<Spanned<OneOrMany<Name>>>,
377    pub config: Option<Spanned<OneOrMany<Name>>>,
378    pub from: Spanned<OneOrMany<ExposeFromRef>>,
379    pub to: Option<Spanned<ExposeToRef>>,
380    pub r#as: Option<Spanned<Name>>,
381    pub rights: Option<Spanned<Rights>>,
382    pub subdir: Option<Spanned<RelativePath>>,
383    pub event_stream: Option<Spanned<OneOrMany<Name>>>,
384    pub scope: Option<Spanned<OneOrMany<EventScope>>>,
385    pub availability: Option<Spanned<Availability>>,
386    pub source_availability: Option<Spanned<SourceAvailability>>,
387}
388
389#[derive(Debug, Clone)]
390pub struct ContextExpose {
391    pub origin: Origin,
392    pub service: Option<ContextSpanned<OneOrMany<Name>>>,
393    pub protocol: Option<ContextSpanned<OneOrMany<Name>>>,
394    pub directory: Option<ContextSpanned<OneOrMany<Name>>>,
395    pub runner: Option<ContextSpanned<OneOrMany<Name>>>,
396    pub resolver: Option<ContextSpanned<OneOrMany<Name>>>,
397    pub dictionary: Option<ContextSpanned<OneOrMany<Name>>>,
398    pub config: Option<ContextSpanned<OneOrMany<Name>>>,
399    pub from: ContextSpanned<OneOrMany<ExposeFromRef>>,
400    pub to: Option<ContextSpanned<ExposeToRef>>,
401    pub r#as: Option<ContextSpanned<Name>>,
402    pub rights: Option<ContextSpanned<Rights>>,
403    pub subdir: Option<ContextSpanned<RelativePath>>,
404    pub event_stream: Option<ContextSpanned<OneOrMany<Name>>>,
405    pub scope: Option<ContextSpanned<OneOrMany<EventScope>>>,
406    pub availability: Option<ContextSpanned<Availability>>,
407    pub source_availability: Option<ContextSpanned<SourceAvailability>>,
408}
409
410impl ContextCapabilityClause for ContextExpose {
411    fn service(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
412        option_one_or_many_as_ref_context(&self.service)
413    }
414    fn protocol(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
415        option_one_or_many_as_ref_context(&self.protocol)
416    }
417    fn directory(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
418        option_one_or_many_as_ref_context(&self.directory)
419    }
420    fn storage(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
421        None
422    }
423    fn runner(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
424        option_one_or_many_as_ref_context(&self.runner)
425    }
426    fn resolver(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
427        option_one_or_many_as_ref_context(&self.resolver)
428    }
429    fn event_stream(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
430        option_one_or_many_as_ref_context(&self.event_stream)
431    }
432    fn dictionary(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
433        option_one_or_many_as_ref_context(&self.dictionary)
434    }
435    fn config(&self) -> Option<ContextSpanned<OneOrMany<&BorrowedName>>> {
436        option_one_or_many_as_ref_context(&self.config)
437    }
438
439    fn decl_type(&self) -> &'static str {
440        "expose"
441    }
442    fn supported(&self) -> &[&'static str] {
443        &[
444            "service",
445            "protocol",
446            "directory",
447            "event_stream",
448            "runner",
449            "resolver",
450            "config",
451            "dicitionary",
452        ]
453    }
454    fn are_many_names_allowed(&self) -> bool {
455        [
456            "service",
457            "protocol",
458            "directory",
459            "runner",
460            "resolver",
461            "event_stream",
462            "config",
463            "dicitionary",
464        ]
465        .contains(&self.capability_type(None).unwrap())
466    }
467
468    fn set_service(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
469        self.service = o;
470    }
471    fn set_protocol(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
472        self.protocol = o;
473    }
474    fn set_directory(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
475        self.directory = o;
476    }
477    fn set_storage(&mut self, _o: Option<ContextSpanned<OneOrMany<Name>>>) {}
478    fn set_runner(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
479        self.runner = o;
480    }
481    fn set_resolver(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
482        self.resolver = o;
483    }
484    fn set_event_stream(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
485        self.event_stream = o;
486    }
487    fn set_dictionary(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
488        self.dictionary = o;
489    }
490    fn set_config(&mut self, o: Option<ContextSpanned<OneOrMany<Name>>>) {
491        self.config = o;
492    }
493
494    fn origin(&self) -> &Origin {
495        &self.origin
496    }
497
498    /// Helper to get the file path from the origin.
499    fn file_path(&self) -> PathBuf {
500        (*self.origin.file).clone()
501    }
502}
503
504impl PartialEq for ContextExpose {
505    fn eq(&self, other: &Self) -> bool {
506        macro_rules! cmp {
507            ($field:ident) => {
508                match (&self.$field, &other.$field) {
509                    (Some(a), Some(b)) => a.value == b.value,
510                    (None, None) => true,
511                    _ => false,
512                }
513            };
514        }
515
516        cmp!(service)
517            && cmp!(protocol)
518            && cmp!(directory)
519            && cmp!(runner)
520            && cmp!(resolver)
521            && cmp!(dictionary)
522            && cmp!(config)
523            && self.from.value == other.from.value
524            && cmp!(to)
525            && cmp!(r#as)
526            && cmp!(rights)
527            && cmp!(subdir)
528            && cmp!(event_stream)
529            && cmp!(scope)
530            && cmp!(availability)
531            && cmp!(source_availability)
532    }
533}
534
535impl Eq for ContextExpose {}
536
537impl ContextPathClause for ContextExpose {
538    fn path(&self) -> Option<&ContextSpanned<Path>> {
539        None
540    }
541}
542
543impl AsClauseContext for ContextExpose {
544    fn r#as(&self) -> Option<ContextSpanned<&BorrowedName>> {
545        self.r#as.as_ref().map(|spanned_name| ContextSpanned {
546            value: spanned_name.value.as_ref(),
547            origin: spanned_name.origin.clone(),
548        })
549    }
550}
551
552impl FromClauseContext for ContextExpose {
553    fn from_(&self) -> ContextSpanned<OneOrMany<AnyRef<'_>>> {
554        one_or_many_from_context(&self.from)
555    }
556}
557
558impl Hydrate for ParsedExpose {
559    type Output = ContextExpose;
560
561    fn hydrate(self, file: &Arc<PathBuf>, buffer: &String) -> Result<Self::Output, Error> {
562        Ok(ContextExpose {
563            origin: Origin::synthetic(file.clone().to_path_buf()),
564            service: hydrate_opt_simple(self.service, file, buffer),
565            protocol: hydrate_opt_simple(self.protocol, file, buffer),
566            directory: hydrate_opt_simple(self.directory, file, buffer),
567            runner: hydrate_opt_simple(self.runner, file, buffer),
568            resolver: hydrate_opt_simple(self.resolver, file, buffer),
569            dictionary: hydrate_opt_simple(self.dictionary, file, buffer),
570            config: hydrate_opt_simple(self.config, file, buffer),
571            from: hydrate_simple(self.from, file, buffer),
572            to: hydrate_opt_simple(self.to, file, buffer),
573            r#as: hydrate_opt_simple(self.r#as, file, buffer),
574            rights: hydrate_opt_simple(self.rights, file, buffer),
575            subdir: hydrate_opt_simple(self.subdir, file, buffer),
576            event_stream: hydrate_opt_simple(self.event_stream, file, buffer),
577            scope: hydrate_opt_simple(self.scope, file, buffer),
578            availability: hydrate_opt_simple(self.availability, file, buffer),
579            source_availability: hydrate_opt_simple(self.source_availability, file, buffer),
580        })
581    }
582}
cml/types/expose.rs

cml/types/
expose.rs
