wasm_encoder/component/
types.rs

1use super::CORE_TYPE_SORT;
2use crate::{
3    encode_section, Alias, ComponentExportKind, ComponentOuterAliasKind, ComponentSection,
4    ComponentSectionId, ComponentTypeRef, CoreTypeEncoder, Encode, EntityType, ValType,
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    params_encoded: bool,
357    results_encoded: bool,
358    sink: &'a mut Vec<u8>,
359}
360
361impl<'a> ComponentFuncTypeEncoder<'a> {
362    fn new(sink: &'a mut Vec<u8>) -> Self {
363        sink.push(0x40);
364        Self {
365            params_encoded: false,
366            results_encoded: false,
367            sink,
368        }
369    }
370
371    /// Defines named parameters.
372    ///
373    /// Parameters must be defined before defining results.
374    ///
375    /// # Panics
376    ///
377    /// This method will panic if the function is called twice since parameters
378    /// can only be encoded once.
379    pub fn params<'b, P, T>(&mut self, params: P) -> &mut Self
380    where
381        P: IntoIterator<Item = (&'b str, T)>,
382        P::IntoIter: ExactSizeIterator,
383        T: Into<ComponentValType>,
384    {
385        assert!(!self.params_encoded);
386        self.params_encoded = true;
387        let params = params.into_iter();
388        params.len().encode(self.sink);
389        for (name, ty) in params {
390            name.encode(self.sink);
391            ty.into().encode(self.sink);
392        }
393        self
394    }
395
396    /// Defines a single unnamed result.
397    ///
398    /// This method cannot be used with `results`.
399    ///
400    /// # Panics
401    ///
402    /// This method will panic if the function is called twice, called before
403    /// the `params` method, or called in addition to the `results` method.
404    pub fn result(&mut self, ty: Option<ComponentValType>) -> &mut Self {
405        assert!(self.params_encoded);
406        assert!(!self.results_encoded);
407        self.results_encoded = true;
408        encode_resultlist(self.sink, ty);
409        self
410    }
411}
412
413pub(crate) fn encode_resultlist(sink: &mut Vec<u8>, ty: Option<ComponentValType>) {
414    match ty {
415        Some(ty) => {
416            sink.push(0x00);
417            ty.encode(sink);
418        }
419        None => {
420            sink.push(0x01);
421            sink.push(0x00);
422        }
423    }
424}
425
426/// Used to encode component and instance types.
427#[derive(Debug)]
428pub struct ComponentTypeEncoder<'a>(&'a mut Vec<u8>);
429
430impl<'a> ComponentTypeEncoder<'a> {
431    /// Define a component type.
432    pub fn component(self, ty: &ComponentType) {
433        ty.encode(self.0);
434    }
435
436    /// Define an instance type.
437    pub fn instance(self, ty: &InstanceType) {
438        ty.encode(self.0);
439    }
440
441    /// Define a function type.
442    pub fn function(self) -> ComponentFuncTypeEncoder<'a> {
443        ComponentFuncTypeEncoder::new(self.0)
444    }
445
446    /// Define a defined component type.
447    ///
448    /// The returned encoder must be used before adding another type.
449    #[must_use = "the encoder must be used to encode the type"]
450    pub fn defined_type(self) -> ComponentDefinedTypeEncoder<'a> {
451        ComponentDefinedTypeEncoder(self.0)
452    }
453
454    /// Define a resource type.
455    pub fn resource(self, rep: ValType, dtor: Option<u32>) {
456        self.0.push(0x3f);
457        rep.encode(self.0);
458        match dtor {
459            Some(i) => {
460                self.0.push(0x01);
461                i.encode(self.0);
462            }
463            None => self.0.push(0x00),
464        }
465    }
466}
467
468/// Represents a primitive component value type.
469#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
470pub enum PrimitiveValType {
471    /// The type is a boolean.
472    Bool,
473    /// The type is a signed 8-bit integer.
474    S8,
475    /// The type is an unsigned 8-bit integer.
476    U8,
477    /// The type is a signed 16-bit integer.
478    S16,
479    /// The type is an unsigned 16-bit integer.
480    U16,
481    /// The type is a signed 32-bit integer.
482    S32,
483    /// The type is an unsigned 32-bit integer.
484    U32,
485    /// The type is a signed 64-bit integer.
486    S64,
487    /// The type is an unsigned 64-bit integer.
488    U64,
489    /// The type is a 32-bit floating point number with only one NaN.
490    F32,
491    /// The type is a 64-bit floating point number with only one NaN.
492    F64,
493    /// The type is a Unicode character.
494    Char,
495    /// The type is a string.
496    String,
497    /// Type for `error-context` added with async support in the component model.
498    ErrorContext,
499}
500
501impl Encode for PrimitiveValType {
502    fn encode(&self, sink: &mut Vec<u8>) {
503        sink.push(match self {
504            Self::Bool => 0x7f,
505            Self::S8 => 0x7e,
506            Self::U8 => 0x7d,
507            Self::S16 => 0x7c,
508            Self::U16 => 0x7b,
509            Self::S32 => 0x7a,
510            Self::U32 => 0x79,
511            Self::S64 => 0x78,
512            Self::U64 => 0x77,
513            Self::F32 => 0x76,
514            Self::F64 => 0x75,
515            Self::Char => 0x74,
516            Self::String => 0x73,
517            Self::ErrorContext => 0x64,
518        });
519    }
520}
521
522/// Represents a component value type.
523#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
524pub enum ComponentValType {
525    /// The value is a primitive type.
526    Primitive(PrimitiveValType),
527    /// The value is to a defined value type.
528    ///
529    /// The type index must be to a value type.
530    Type(u32),
531}
532
533impl Encode for ComponentValType {
534    fn encode(&self, sink: &mut Vec<u8>) {
535        match self {
536            Self::Primitive(ty) => ty.encode(sink),
537            Self::Type(index) => (*index as i64).encode(sink),
538        }
539    }
540}
541
542impl From<PrimitiveValType> for ComponentValType {
543    fn from(ty: PrimitiveValType) -> Self {
544        Self::Primitive(ty)
545    }
546}
547
548/// Used for encoding component defined types.
549#[derive(Debug)]
550pub struct ComponentDefinedTypeEncoder<'a>(&'a mut Vec<u8>);
551
552impl ComponentDefinedTypeEncoder<'_> {
553    /// Define a primitive value type.
554    pub fn primitive(self, ty: PrimitiveValType) {
555        ty.encode(self.0);
556    }
557
558    /// Define a record type.
559    pub fn record<'a, F, T>(self, fields: F)
560    where
561        F: IntoIterator<Item = (&'a str, T)>,
562        F::IntoIter: ExactSizeIterator,
563        T: Into<ComponentValType>,
564    {
565        let fields = fields.into_iter();
566        self.0.push(0x72);
567        fields.len().encode(self.0);
568        for (name, ty) in fields {
569            name.encode(self.0);
570            ty.into().encode(self.0);
571        }
572    }
573
574    /// Define a variant type.
575    pub fn variant<'a, C>(self, cases: C)
576    where
577        C: IntoIterator<Item = (&'a str, Option<ComponentValType>, Option<u32>)>,
578        C::IntoIter: ExactSizeIterator,
579    {
580        let cases = cases.into_iter();
581        self.0.push(0x71);
582        cases.len().encode(self.0);
583        for (name, ty, refines) in cases {
584            name.encode(self.0);
585            ty.encode(self.0);
586            refines.encode(self.0);
587        }
588    }
589
590    /// Define a list type.
591    pub fn list(self, ty: impl Into<ComponentValType>) {
592        self.0.push(0x70);
593        ty.into().encode(self.0);
594    }
595
596    /// Define a tuple type.
597    pub fn tuple<I, T>(self, types: I)
598    where
599        I: IntoIterator<Item = T>,
600        I::IntoIter: ExactSizeIterator,
601        T: Into<ComponentValType>,
602    {
603        let types = types.into_iter();
604        self.0.push(0x6F);
605        types.len().encode(self.0);
606        for ty in types {
607            ty.into().encode(self.0);
608        }
609    }
610
611    /// Define a flags type.
612    pub fn flags<'a, I>(self, names: I)
613    where
614        I: IntoIterator<Item = &'a str>,
615        I::IntoIter: ExactSizeIterator,
616    {
617        let names = names.into_iter();
618        self.0.push(0x6E);
619        names.len().encode(self.0);
620        for name in names {
621            name.encode(self.0);
622        }
623    }
624
625    /// Define an enum type.
626    pub fn enum_type<'a, I>(self, tags: I)
627    where
628        I: IntoIterator<Item = &'a str>,
629        I::IntoIter: ExactSizeIterator,
630    {
631        let tags = tags.into_iter();
632        self.0.push(0x6D);
633        tags.len().encode(self.0);
634        for tag in tags {
635            tag.encode(self.0);
636        }
637    }
638
639    /// Define an option type.
640    pub fn option(self, ty: impl Into<ComponentValType>) {
641        self.0.push(0x6B);
642        ty.into().encode(self.0);
643    }
644
645    /// Define a result type.
646    pub fn result(self, ok: Option<ComponentValType>, err: Option<ComponentValType>) {
647        self.0.push(0x6A);
648        ok.encode(self.0);
649        err.encode(self.0);
650    }
651
652    /// Define a `own` handle type
653    pub fn own(self, idx: u32) {
654        self.0.push(0x69);
655        idx.encode(self.0);
656    }
657
658    /// Define a `borrow` handle type
659    pub fn borrow(self, idx: u32) {
660        self.0.push(0x68);
661        idx.encode(self.0);
662    }
663
664    /// Define a `future` type with the specified payload.
665    pub fn future(self, payload: Option<ComponentValType>) {
666        self.0.push(0x65);
667        payload.encode(self.0);
668    }
669
670    /// Define a `stream` type with the specified payload.
671    pub fn stream(self, payload: Option<ComponentValType>) {
672        self.0.push(0x66);
673        payload.encode(self.0);
674    }
675}
676
677/// An encoder for the type section of WebAssembly components.
678///
679/// # Example
680///
681/// ```rust
682/// use wasm_encoder::{Component, ComponentTypeSection, PrimitiveValType};
683///
684/// let mut types = ComponentTypeSection::new();
685///
686/// // Define a function type of `[string, string] -> string`.
687/// types
688///   .function()
689///   .params(
690///     [
691///       ("a", PrimitiveValType::String),
692///       ("b", PrimitiveValType::String)
693///     ]
694///   )
695///   .result(Some(PrimitiveValType::String.into()));
696///
697/// let mut component = Component::new();
698/// component.section(&types);
699///
700/// let bytes = component.finish();
701/// ```
702#[derive(Clone, Debug, Default)]
703pub struct ComponentTypeSection {
704    bytes: Vec<u8>,
705    num_added: u32,
706}
707
708impl ComponentTypeSection {
709    /// Create a new component type section encoder.
710    pub fn new() -> Self {
711        Self::default()
712    }
713
714    /// The number of types in the section.
715    pub fn len(&self) -> u32 {
716        self.num_added
717    }
718
719    /// Determines if the section is empty.
720    pub fn is_empty(&self) -> bool {
721        self.num_added == 0
722    }
723
724    /// Encode a type into this section.
725    ///
726    /// The returned encoder must be finished before adding another type.
727    #[must_use = "the encoder must be used to encode the type"]
728    pub fn ty(&mut self) -> ComponentTypeEncoder<'_> {
729        self.num_added += 1;
730        ComponentTypeEncoder(&mut self.bytes)
731    }
732
733    /// Define a component type in this type section.
734    pub fn component(&mut self, ty: &ComponentType) -> &mut Self {
735        self.ty().component(ty);
736        self
737    }
738
739    /// Define an instance type in this type section.
740    pub fn instance(&mut self, ty: &InstanceType) -> &mut Self {
741        self.ty().instance(ty);
742        self
743    }
744
745    /// Define a function type in this type section.
746    pub fn function(&mut self) -> ComponentFuncTypeEncoder<'_> {
747        self.ty().function()
748    }
749
750    /// Add a component defined type to this type section.
751    ///
752    /// The returned encoder must be used before adding another type.
753    #[must_use = "the encoder must be used to encode the type"]
754    pub fn defined_type(&mut self) -> ComponentDefinedTypeEncoder<'_> {
755        self.ty().defined_type()
756    }
757
758    /// Defines a new resource type.
759    pub fn resource(&mut self, rep: ValType, dtor: Option<u32>) -> &mut Self {
760        self.ty().resource(rep, dtor);
761        self
762    }
763}
764
765impl Encode for ComponentTypeSection {
766    fn encode(&self, sink: &mut Vec<u8>) {
767        encode_section(sink, self.num_added, &self.bytes);
768    }
769}
770
771impl ComponentSection for ComponentTypeSection {
772    fn id(&self) -> u8 {
773        ComponentSectionId::Type.into()
774    }
775}
wasm_encoder/component/types.rs

wasm_encoder/component/
types.rs
