wasm_encoder/component/
types.rs

1use super::CORE_TYPE_SORT;
2use crate::{
3    Alias, ComponentExportKind, ComponentOuterAliasKind, ComponentSection, ComponentSectionId,
4    ComponentTypeRef, CoreTypeEncoder, Encode, EntityType, ValType, encode_section,
5};
6use alloc::vec::Vec;
7
8/// Represents the type of a core module.
9#[derive(Debug, Clone, Default)]
10pub struct ModuleType {
11    bytes: Vec<u8>,
12    num_added: u32,
13    types_added: u32,
14}
15
16impl ModuleType {
17    /// Creates a new core module type.
18    pub fn new() -> Self {
19        Self::default()
20    }
21
22    /// Defines an import in this module type.
23    pub fn import(&mut self, module: &str, name: &str, ty: EntityType) -> &mut Self {
24        self.bytes.push(0x00);
25        module.encode(&mut self.bytes);
26        name.encode(&mut self.bytes);
27        ty.encode(&mut self.bytes);
28        self.num_added += 1;
29        self
30    }
31
32    /// Define a type in this module type.
33    ///
34    /// The returned encoder must be used before adding another definition.
35    #[must_use = "the encoder must be used to encode the type"]
36    pub fn ty(&mut self) -> CoreTypeEncoder<'_> {
37        self.bytes.push(0x01);
38        self.num_added += 1;
39        self.types_added += 1;
40        CoreTypeEncoder {
41            push_prefix_if_component_core_type: false,
42            bytes: &mut self.bytes,
43        }
44    }
45
46    /// Defines an outer core type alias in this module type.
47    pub fn alias_outer_core_type(&mut self, count: u32, index: u32) -> &mut Self {
48        self.bytes.push(0x02);
49        self.bytes.push(CORE_TYPE_SORT);
50        self.bytes.push(0x01); // outer
51        count.encode(&mut self.bytes);
52        index.encode(&mut self.bytes);
53        self.num_added += 1;
54        self.types_added += 1;
55        self
56    }
57
58    /// Defines an export in this module type.
59    pub fn export(&mut self, name: &str, ty: EntityType) -> &mut Self {
60        self.bytes.push(0x03);
61        name.encode(&mut self.bytes);
62        ty.encode(&mut self.bytes);
63        self.num_added += 1;
64        self
65    }
66
67    /// Gets the number of types that have been added to this module type.
68    pub fn type_count(&self) -> u32 {
69        self.types_added
70    }
71}
72
73impl Encode for ModuleType {
74    fn encode(&self, sink: &mut Vec<u8>) {
75        sink.push(0x50);
76        self.num_added.encode(sink);
77        sink.extend(&self.bytes);
78    }
79}
80
81/// Used to encode core types.
82#[derive(Debug)]
83pub struct ComponentCoreTypeEncoder<'a>(pub(crate) &'a mut Vec<u8>);
84
85impl<'a> ComponentCoreTypeEncoder<'a> {
86    /// Define a module type.
87    pub fn module(self, ty: &ModuleType) {
88        ty.encode(self.0);
89    }
90
91    /// Define any core type other than a module type.
92    #[must_use = "the encoder must be used to encode the type"]
93    pub fn core(self) -> CoreTypeEncoder<'a> {
94        CoreTypeEncoder {
95            bytes: self.0,
96            push_prefix_if_component_core_type: true,
97        }
98    }
99}
100
101/// An encoder for the core type section of WebAssembly components.
102///
103/// # Example
104///
105/// ```rust
106/// use wasm_encoder::{Component, CoreTypeSection, ModuleType};
107///
108/// let mut types = CoreTypeSection::new();
109///
110/// types.ty().module(&ModuleType::new());
111///
112/// let mut component = Component::new();
113/// component.section(&types);
114///
115/// let bytes = component.finish();
116/// ```
117#[derive(Clone, Debug, Default)]
118pub struct CoreTypeSection {
119    bytes: Vec<u8>,
120    num_added: u32,
121}
122
123impl CoreTypeSection {
124    /// Create a new core type section encoder.
125    pub fn new() -> Self {
126        Self::default()
127    }
128
129    /// The number of types in the section.
130    pub fn len(&self) -> u32 {
131        self.num_added
132    }
133
134    /// Determines if the section is empty.
135    pub fn is_empty(&self) -> bool {
136        self.num_added == 0
137    }
138
139    /// Encode a type into this section.
140    ///
141    /// The returned encoder must be finished before adding another type.
142    #[must_use = "the encoder must be used to encode the type"]
143    pub fn ty(&mut self) -> ComponentCoreTypeEncoder<'_> {
144        self.num_added += 1;
145        ComponentCoreTypeEncoder(&mut self.bytes)
146    }
147}
148
149impl Encode for CoreTypeSection {
150    fn encode(&self, sink: &mut Vec<u8>) {
151        encode_section(sink, self.num_added, &self.bytes);
152    }
153}
154
155impl ComponentSection for CoreTypeSection {
156    fn id(&self) -> u8 {
157        ComponentSectionId::CoreType.into()
158    }
159}
160
161/// Represents a component type.
162#[derive(Debug, Clone, Default)]
163pub struct ComponentType {
164    bytes: Vec<u8>,
165    num_added: u32,
166    core_types_added: u32,
167    types_added: u32,
168    instances_added: u32,
169}
170
171impl ComponentType {
172    /// Creates a new component type.
173    pub fn new() -> Self {
174        Self::default()
175    }
176
177    /// Define a core type in this component type.
178    ///
179    /// The returned encoder must be used before adding another definition.
180    #[must_use = "the encoder must be used to encode the type"]
181    pub fn core_type(&mut self) -> ComponentCoreTypeEncoder<'_> {
182        self.bytes.push(0x00);
183        self.num_added += 1;
184        self.core_types_added += 1;
185        ComponentCoreTypeEncoder(&mut self.bytes)
186    }
187
188    /// Define a type in this component type.
189    ///
190    /// The returned encoder must be used before adding another definition.
191    #[must_use = "the encoder must be used to encode the type"]
192    pub fn ty(&mut self) -> ComponentTypeEncoder<'_> {
193        self.bytes.push(0x01);
194        self.num_added += 1;
195        self.types_added += 1;
196        ComponentTypeEncoder(&mut self.bytes)
197    }
198
199    /// Defines an alias for an exported item of a prior instance or an
200    /// outer type.
201    pub fn alias(&mut self, alias: Alias<'_>) -> &mut Self {
202        self.bytes.push(0x02);
203        alias.encode(&mut self.bytes);
204        self.num_added += 1;
205        match &alias {
206            Alias::InstanceExport {
207                kind: ComponentExportKind::Type,
208                ..
209            }
210            | Alias::Outer {
211                kind: ComponentOuterAliasKind::Type,
212                ..
213            } => self.types_added += 1,
214            Alias::Outer {
215                kind: ComponentOuterAliasKind::CoreType,
216                ..
217            } => self.core_types_added += 1,
218            Alias::InstanceExport {
219                kind: ComponentExportKind::Instance,
220                ..
221            } => self.instances_added += 1,
222            _ => {}
223        }
224        self
225    }
226
227    /// Defines an import in this component type.
228    pub fn import(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
229        self.bytes.push(0x03);
230        crate::encode_component_import_name(&mut self.bytes, name);
231        ty.encode(&mut self.bytes);
232        self.num_added += 1;
233        match ty {
234            ComponentTypeRef::Type(..) => self.types_added += 1,
235            ComponentTypeRef::Instance(..) => self.instances_added += 1,
236            _ => {}
237        }
238        self
239    }
240
241    /// Defines an export in this component type.
242    pub fn export(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
243        self.bytes.push(0x04);
244        crate::encode_component_export_name(&mut self.bytes, name);
245        ty.encode(&mut self.bytes);
246        self.num_added += 1;
247        match ty {
248            ComponentTypeRef::Type(..) => self.types_added += 1,
249            ComponentTypeRef::Instance(..) => self.instances_added += 1,
250            _ => {}
251        }
252        self
253    }
254
255    /// Gets the number of core types that have been added to this component type.
256    pub fn core_type_count(&self) -> u32 {
257        self.core_types_added
258    }
259
260    /// Gets the number of types that have been added or aliased in this component type.
261    pub fn type_count(&self) -> u32 {
262        self.types_added
263    }
264
265    /// Gets the number of instances that have been defined in this component
266    /// type through imports, exports, or aliases.
267    pub fn instance_count(&self) -> u32 {
268        self.instances_added
269    }
270}
271
272impl Encode for ComponentType {
273    fn encode(&self, sink: &mut Vec<u8>) {
274        sink.push(0x41);
275        self.num_added.encode(sink);
276        sink.extend(&self.bytes);
277    }
278}
279
280/// Represents an instance type.
281#[derive(Debug, Clone, Default)]
282pub struct InstanceType(ComponentType);
283
284impl InstanceType {
285    /// Creates a new instance type.
286    pub fn new() -> Self {
287        Self::default()
288    }
289
290    /// Define a core type in this instance type.
291    ///
292    /// The returned encoder must be used before adding another definition.
293    #[must_use = "the encoder must be used to encode the type"]
294    pub fn core_type(&mut self) -> ComponentCoreTypeEncoder<'_> {
295        self.0.core_type()
296    }
297
298    /// Define a type in this instance type.
299    ///
300    /// The returned encoder must be used before adding another definition.
301    #[must_use = "the encoder must be used to encode the type"]
302    pub fn ty(&mut self) -> ComponentTypeEncoder<'_> {
303        self.0.ty()
304    }
305
306    /// Defines an outer core type alias in this component type.
307    pub fn alias(&mut self, alias: Alias<'_>) -> &mut Self {
308        self.0.alias(alias);
309        self
310    }
311
312    /// Defines an export in this instance type.
313    pub fn export(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
314        self.0.export(name, ty);
315        self
316    }
317
318    /// Gets the number of core types that have been added to this instance type.
319    pub fn core_type_count(&self) -> u32 {
320        self.0.core_types_added
321    }
322
323    /// Gets the number of types that have been added or aliased in this instance type.
324    pub fn type_count(&self) -> u32 {
325        self.0.types_added
326    }
327
328    /// Gets the number of instances that have been imported or exported or
329    /// aliased in this instance type.
330    pub fn instance_count(&self) -> u32 {
331        self.0.instances_added
332    }
333
334    /// Returns whether or not this instance type is empty.
335    pub fn is_empty(&self) -> bool {
336        self.0.num_added == 0
337    }
338
339    /// Returns the number of entries added to this instance types.
340    pub fn len(&self) -> u32 {
341        self.0.num_added
342    }
343}
344
345impl Encode for InstanceType {
346    fn encode(&self, sink: &mut Vec<u8>) {
347        sink.push(0x42);
348        self.0.num_added.encode(sink);
349        sink.extend(&self.0.bytes);
350    }
351}
352
353/// Used to encode component function types.
354#[derive(Debug)]
355pub struct ComponentFuncTypeEncoder<'a> {
356    async_encoded: bool,
357    params_encoded: bool,
358    results_encoded: bool,
359    sink: &'a mut Vec<u8>,
360}
361
362impl<'a> ComponentFuncTypeEncoder<'a> {
363    fn new(sink: &'a mut Vec<u8>) -> Self {
364        Self {
365            async_encoded: false,
366            params_encoded: false,
367            results_encoded: false,
368            sink,
369        }
370    }
371
372    /// Indicates whether this is an `async` function or not.
373    ///
374    /// If this function is not invoked then the function type will not be
375    /// `async`.
376    ///
377    /// # Panics
378    ///
379    /// This method will panic if parameters or results have already been
380    /// encoded.
381    pub fn async_(&mut self, is_async: bool) -> &mut Self {
382        assert!(!self.params_encoded);
383        assert!(!self.results_encoded);
384        assert!(!self.async_encoded);
385        self.async_encoded = true;
386        if is_async {
387            self.sink.push(0x43);
388        } else {
389            self.sink.push(0x40);
390        }
391        self
392    }
393
394    /// Defines named parameters.
395    ///
396    /// Parameters must be defined before defining results.
397    ///
398    /// # Panics
399    ///
400    /// This method will panic if the function is called twice since parameters
401    /// can only be encoded once.
402    pub fn params<'b, P, T>(&mut self, params: P) -> &mut Self
403    where
404        P: IntoIterator<Item = (&'b str, T)>,
405        P::IntoIter: ExactSizeIterator,
406        T: Into<ComponentValType>,
407    {
408        assert!(!self.params_encoded);
409        if !self.async_encoded {
410            self.async_(false);
411        }
412        self.params_encoded = true;
413        let params = params.into_iter();
414        params.len().encode(self.sink);
415        for (name, ty) in params {
416            name.encode(self.sink);
417            ty.into().encode(self.sink);
418        }
419        self
420    }
421
422    /// Defines a single unnamed result.
423    ///
424    /// This method cannot be used with `results`.
425    ///
426    /// # Panics
427    ///
428    /// This method will panic if the function is called twice, called before
429    /// the `params` method, or called in addition to the `results` method.
430    pub fn result(&mut self, ty: Option<ComponentValType>) -> &mut Self {
431        assert!(self.async_encoded);
432        assert!(self.params_encoded);
433        assert!(!self.results_encoded);
434        self.results_encoded = true;
435        encode_resultlist(self.sink, ty);
436        self
437    }
438}
439
440pub(crate) fn encode_resultlist(sink: &mut Vec<u8>, ty: Option<ComponentValType>) {
441    match ty {
442        Some(ty) => {
443            sink.push(0x00);
444            ty.encode(sink);
445        }
446        None => {
447            sink.push(0x01);
448            sink.push(0x00);
449        }
450    }
451}
452
453/// Used to encode component and instance types.
454#[derive(Debug)]
455pub struct ComponentTypeEncoder<'a>(&'a mut Vec<u8>);
456
457impl<'a> ComponentTypeEncoder<'a> {
458    /// Define a component type.
459    pub fn component(self, ty: &ComponentType) {
460        ty.encode(self.0);
461    }
462
463    /// Define an instance type.
464    pub fn instance(self, ty: &InstanceType) {
465        ty.encode(self.0);
466    }
467
468    /// Define a function type.
469    pub fn function(self) -> ComponentFuncTypeEncoder<'a> {
470        ComponentFuncTypeEncoder::new(self.0)
471    }
472
473    /// Define a defined component type.
474    ///
475    /// The returned encoder must be used before adding another type.
476    #[must_use = "the encoder must be used to encode the type"]
477    pub fn defined_type(self) -> ComponentDefinedTypeEncoder<'a> {
478        ComponentDefinedTypeEncoder(self.0)
479    }
480
481    /// Define a resource type.
482    pub fn resource(self, rep: ValType, dtor: Option<u32>) {
483        self.0.push(0x3f);
484        rep.encode(self.0);
485        match dtor {
486            Some(i) => {
487                self.0.push(0x01);
488                i.encode(self.0);
489            }
490            None => self.0.push(0x00),
491        }
492    }
493}
494
495/// Represents a primitive component value type.
496#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
497pub enum PrimitiveValType {
498    /// The type is a boolean.
499    Bool,
500    /// The type is a signed 8-bit integer.
501    S8,
502    /// The type is an unsigned 8-bit integer.
503    U8,
504    /// The type is a signed 16-bit integer.
505    S16,
506    /// The type is an unsigned 16-bit integer.
507    U16,
508    /// The type is a signed 32-bit integer.
509    S32,
510    /// The type is an unsigned 32-bit integer.
511    U32,
512    /// The type is a signed 64-bit integer.
513    S64,
514    /// The type is an unsigned 64-bit integer.
515    U64,
516    /// The type is a 32-bit floating point number with only one NaN.
517    F32,
518    /// The type is a 64-bit floating point number with only one NaN.
519    F64,
520    /// The type is a Unicode character.
521    Char,
522    /// The type is a string.
523    String,
524    /// Type for `error-context` added with async support in the component model.
525    ErrorContext,
526}
527
528impl Encode for PrimitiveValType {
529    fn encode(&self, sink: &mut Vec<u8>) {
530        sink.push(match self {
531            Self::Bool => 0x7f,
532            Self::S8 => 0x7e,
533            Self::U8 => 0x7d,
534            Self::S16 => 0x7c,
535            Self::U16 => 0x7b,
536            Self::S32 => 0x7a,
537            Self::U32 => 0x79,
538            Self::S64 => 0x78,
539            Self::U64 => 0x77,
540            Self::F32 => 0x76,
541            Self::F64 => 0x75,
542            Self::Char => 0x74,
543            Self::String => 0x73,
544            Self::ErrorContext => 0x64,
545        });
546    }
547}
548
549/// Represents a component value type.
550#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
551pub enum ComponentValType {
552    /// The value is a primitive type.
553    Primitive(PrimitiveValType),
554    /// The value is to a defined value type.
555    ///
556    /// The type index must be to a value type.
557    Type(u32),
558}
559
560impl Encode for ComponentValType {
561    fn encode(&self, sink: &mut Vec<u8>) {
562        match self {
563            Self::Primitive(ty) => ty.encode(sink),
564            Self::Type(index) => (*index as i64).encode(sink),
565        }
566    }
567}
568
569impl From<PrimitiveValType> for ComponentValType {
570    fn from(ty: PrimitiveValType) -> Self {
571        Self::Primitive(ty)
572    }
573}
574
575/// Used for encoding component defined types.
576#[derive(Debug)]
577pub struct ComponentDefinedTypeEncoder<'a>(&'a mut Vec<u8>);
578
579impl ComponentDefinedTypeEncoder<'_> {
580    /// Define a primitive value type.
581    pub fn primitive(self, ty: PrimitiveValType) {
582        ty.encode(self.0);
583    }
584
585    /// Define a record type.
586    pub fn record<'a, F, T>(self, fields: F)
587    where
588        F: IntoIterator<Item = (&'a str, T)>,
589        F::IntoIter: ExactSizeIterator,
590        T: Into<ComponentValType>,
591    {
592        let fields = fields.into_iter();
593        self.0.push(0x72);
594        fields.len().encode(self.0);
595        for (name, ty) in fields {
596            name.encode(self.0);
597            ty.into().encode(self.0);
598        }
599    }
600
601    /// Define a variant type.
602    pub fn variant<'a, C>(self, cases: C)
603    where
604        C: IntoIterator<Item = (&'a str, Option<ComponentValType>, Option<u32>)>,
605        C::IntoIter: ExactSizeIterator,
606    {
607        let cases = cases.into_iter();
608        self.0.push(0x71);
609        cases.len().encode(self.0);
610        for (name, ty, refines) in cases {
611            name.encode(self.0);
612            ty.encode(self.0);
613            refines.encode(self.0);
614        }
615    }
616
617    /// Define a list type.
618    pub fn list(self, ty: impl Into<ComponentValType>) {
619        self.0.push(0x70);
620        ty.into().encode(self.0);
621    }
622
623    /// Define a fixed size list type.
624    pub fn fixed_size_list(self, ty: impl Into<ComponentValType>, elements: u32) {
625        self.0.push(0x67);
626        ty.into().encode(self.0);
627        elements.encode(self.0);
628    }
629
630    /// Define a tuple type.
631    pub fn tuple<I, T>(self, types: I)
632    where
633        I: IntoIterator<Item = T>,
634        I::IntoIter: ExactSizeIterator,
635        T: Into<ComponentValType>,
636    {
637        let types = types.into_iter();
638        self.0.push(0x6F);
639        types.len().encode(self.0);
640        for ty in types {
641            ty.into().encode(self.0);
642        }
643    }
644
645    /// Define a flags type.
646    pub fn flags<'a, I>(self, names: I)
647    where
648        I: IntoIterator<Item = &'a str>,
649        I::IntoIter: ExactSizeIterator,
650    {
651        let names = names.into_iter();
652        self.0.push(0x6E);
653        names.len().encode(self.0);
654        for name in names {
655            name.encode(self.0);
656        }
657    }
658
659    /// Define an enum type.
660    pub fn enum_type<'a, I>(self, tags: I)
661    where
662        I: IntoIterator<Item = &'a str>,
663        I::IntoIter: ExactSizeIterator,
664    {
665        let tags = tags.into_iter();
666        self.0.push(0x6D);
667        tags.len().encode(self.0);
668        for tag in tags {
669            tag.encode(self.0);
670        }
671    }
672
673    /// Define an option type.
674    pub fn option(self, ty: impl Into<ComponentValType>) {
675        self.0.push(0x6B);
676        ty.into().encode(self.0);
677    }
678
679    /// Define a result type.
680    pub fn result(self, ok: Option<ComponentValType>, err: Option<ComponentValType>) {
681        self.0.push(0x6A);
682        ok.encode(self.0);
683        err.encode(self.0);
684    }
685
686    /// Define a `own` handle type
687    pub fn own(self, idx: u32) {
688        self.0.push(0x69);
689        idx.encode(self.0);
690    }
691
692    /// Define a `borrow` handle type
693    pub fn borrow(self, idx: u32) {
694        self.0.push(0x68);
695        idx.encode(self.0);
696    }
697
698    /// Define a `future` type with the specified payload.
699    pub fn future(self, payload: Option<ComponentValType>) {
700        self.0.push(0x65);
701        payload.encode(self.0);
702    }
703
704    /// Define a `stream` type with the specified payload.
705    pub fn stream(self, payload: Option<ComponentValType>) {
706        self.0.push(0x66);
707        payload.encode(self.0);
708    }
709}
710
711/// An encoder for the type section of WebAssembly components.
712///
713/// # Example
714///
715/// ```rust
716/// use wasm_encoder::{Component, ComponentTypeSection, PrimitiveValType};
717///
718/// let mut types = ComponentTypeSection::new();
719///
720/// // Define a function type of `[string, string] -> string`.
721/// types
722///   .function()
723///   .params(
724///     [
725///       ("a", PrimitiveValType::String),
726///       ("b", PrimitiveValType::String)
727///     ]
728///   )
729///   .result(Some(PrimitiveValType::String.into()));
730///
731/// let mut component = Component::new();
732/// component.section(&types);
733///
734/// let bytes = component.finish();
735/// ```
736#[derive(Clone, Debug, Default)]
737pub struct ComponentTypeSection {
738    bytes: Vec<u8>,
739    num_added: u32,
740}
741
742impl ComponentTypeSection {
743    /// Create a new component type section encoder.
744    pub fn new() -> Self {
745        Self::default()
746    }
747
748    /// The number of types in the section.
749    pub fn len(&self) -> u32 {
750        self.num_added
751    }
752
753    /// Determines if the section is empty.
754    pub fn is_empty(&self) -> bool {
755        self.num_added == 0
756    }
757
758    /// Encode a type into this section.
759    ///
760    /// The returned encoder must be finished before adding another type.
761    #[must_use = "the encoder must be used to encode the type"]
762    pub fn ty(&mut self) -> ComponentTypeEncoder<'_> {
763        self.num_added += 1;
764        ComponentTypeEncoder(&mut self.bytes)
765    }
766
767    /// Define a component type in this type section.
768    pub fn component(&mut self, ty: &ComponentType) -> &mut Self {
769        self.ty().component(ty);
770        self
771    }
772
773    /// Define an instance type in this type section.
774    pub fn instance(&mut self, ty: &InstanceType) -> &mut Self {
775        self.ty().instance(ty);
776        self
777    }
778
779    /// Define a function type in this type section.
780    pub fn function(&mut self) -> ComponentFuncTypeEncoder<'_> {
781        self.ty().function()
782    }
783
784    /// Add a component defined type to this type section.
785    ///
786    /// The returned encoder must be used before adding another type.
787    #[must_use = "the encoder must be used to encode the type"]
788    pub fn defined_type(&mut self) -> ComponentDefinedTypeEncoder<'_> {
789        self.ty().defined_type()
790    }
791
792    /// Defines a new resource type.
793    pub fn resource(&mut self, rep: ValType, dtor: Option<u32>) -> &mut Self {
794        self.ty().resource(rep, dtor);
795        self
796    }
797}
798
799impl Encode for ComponentTypeSection {
800    fn encode(&self, sink: &mut Vec<u8>) {
801        encode_section(sink, self.num_added, &self.bytes);
802    }
803}
804
805impl ComponentSection for ComponentTypeSection {
806    fn id(&self) -> u8 {
807        ComponentSectionId::Type.into()
808    }
809}
wasm_encoder/component/types.rs

wasm_encoder/component/
types.rs
