Atelier: crate atelier_core

This crate provides a Rust native core model for the AWS Smithy Interface Definition Language.

This crate is the foundation for the Atelier set of crates, and provides the following components:

1. The model structures themselves that represents a Smithy model This is the in-memory representation shared by all Atelier crates and tools.
2. The model builder structures that allow for a fluent and easy construction of a core model.
3. The prelude model containing the set of shapes defined in the Smithy specification.
4. Traits for reading/writing models in different representations.
   1. A model writer that emits a stable line-oriented format useful for capturing test results.
   2. A model writer using Rust's Debug trait.
5. A common error module to be used by all Atelier crates.

Example

The following example demonstrates the builder interface to create a model for a simple service. The service, MessageOfTheDay has a single resource Message. The resource has an identifier for the date, but the read operation does not make the date member required and so will return the message for the current date.

Example - Builder

use atelier_core::builder::traits::ErrorSource;
use atelier_core::model::builder::values::{ArrayBuilder, ObjectBuilder};
use atelier_core::model::builder::{
    Builder, ListBuilder, MemberBuilder, ModelBuilder, OperationBuilder, ResourceBuilder,
    ServiceBuilder, ShapeTraits, SimpleShapeBuilder, StructureBuilder, TraitBuilder,
};
use atelier_core::model::{Identifier, Model, ShapeID};

fn make_model() -> Model {
    ModelBuilder::new(Version::V10, "example.motd")
        .service(
            ServiceBuilder::new("MessageOfTheDay", "2020-06-21")
                .documentation("Provides a Message of the day.")
                .resource("Message")
                .into(),
        )
        .resource(
            ResourceBuilder::new("Message")
                .identifier("date", "Date")
                .read("GetMessage")
                .into(),
        )
        .simple_shape(
            SimpleShapeBuilder::string("Date")
                .apply_trait(traits::pattern(r"^\d\d\d\d\-\d\d-\d\d$"))
                .into(),
        )
        .operation(
            OperationBuilder::new("GetMessage")
                .readonly()
                .input("GetMessageInput")
                .output("GetMessageOutput")
                .error("BadDateValue")
                .into(),
        )
        .structure(
            StructureBuilder::new("GetMessageInput")
                .member("date", "Date")
                .into(),
        )
        .structure(
            StructureBuilder::new("GetMessageOutput")
                .add_member(MemberBuilder::string("message").required().into())
                .into(),
        )
        .structure(
            StructureBuilder::new("BadDateValue")
                .error_source(ErrorSource::Client)
                .add_member(MemberBuilder::string("errorMessage").required().into())
                .into(),
        )
        .into()
}

Runnable Examples

The example weather_builder.rs in the examples directory uses the complete example from the Smithy quick start guide. The examples directory also includes a pair of stand-alone examples, using the semantic model and builder APIs, for the message of the day service shown in the example above.

As usual these can be executed via cargo in the following manner.

$ cargo run --example weather_builder
$ cargo run --example motd_core
$ cargo run --example motd_builder

Changes

Version 0.2.22

• Fix for [bug #31](Model builder ignores operation output member, incorrectly stores input member in output member field).

Version 0.2.21

• Altered the HasIdentity trait to parameterize the identifier type.
  • Added is() method to HasIdentity.
• Implemented HasIdentity for MemberShape.
• Removed unnecessary Shape trait.
• Updated the API for action::Transformer to not consume the source.
• Some documentation clean-up.

Version 0.2.20

• Implemented cargo-atelier's lint and validate should work on models built from multiple namespace files using the model assembler.
  • Updated Model::namespaces to return a HashSet rather than a Vec.

Version 0.2.19

• Changed the ID on MemberShape from ShapeID to Identifier. This matches both the formal BNF for the Smithy IDL and the JSON AST usage.

Version 0.2.18

• Fixed escaping bug for line writer that made cross-platform comparison a pain.

Version 0.2.17

• Fixed add_shape bug, it must allow shapes with a member_id IFF the shape kind is unresolved.

Version 0.2.16

• Fixed resolver bug for the fall-through case and create an unresolved reference.

Version 0.2.14

• Reorganized errors, made the naming and messages consistent and removed unused.

Version 0.2.14

• Made Identifier and ShapeID PartialOrd + Ord.
• Added missing prelude trait identifier.

Version 0.2.13

• Added the "renames" collection to service shapes in the abstract model and corresponding builder.
• Updated LineOrientedWriter with rules for empty arrays and objects.
• Made all syntax values public at top of library.
• All annotation traits use an empty object as value, not None.

Version 0.2.12

• Altered builder logic around "apply" of traits to existing shapes, references, and members.

Version 0.2.11

• All model builders now use TryFrom instead of From to report errors rather than panic.
• Implemented the full Smithy unqualified name resolution, added tests from the core documentation.
• Using new shared atelier-test crate.

Version 0.2.10

• Added new io::lines module with LineOrientedWriter.

Version 0.2.9

• Fixed a bug in Model::add_shape for unresolved shapes.

Version 0.2.8

• Added test cases for merging metadata, shapes, and traits.
• Fixed recursion bug in metadata merge.

Version 0.2.7

• Reworked the Model::add_metadata method to perform the Smithy required merge/conflict checks.
• Reworked the Model::add_shape method to perform the Smithy required shape merge/conflict checks.
• Reworked the HasTraits::apply_with_value method to perform the Smithy required trait merge/conflict checks.
  • Reworked how traits are applied, these are now a HashMap not Vec as Smithy only allows the same trait to be applied once.
• Implemented the Model::merge method.

Version 0.2.6

• Refactored the prelude module, moved the lazy statics out to builder where they are used.
• Made a common implementation of HasTraits for TopLevelShape and MemberShip using a macro.
• Changed Resource::identifiers to be more type specific.

Version 0.2.5

• Added public shape_selector! macro.
• Added PartialEq to all model types to enable more testing.
• Tidied up builder interfaces and added some more trait functions.
• Renamed ExpressionListBuilder to SelectorBuilder.

Version 0.2.3

• Added initial builder types for constructing Selector models.
• Renamed ShapeType::All to ShapeType::Any.

Version 0.2.3

• Added support for constructing Selector models.

Version 0.2.2

• Refactor: added HasIdentity and HasTraits traits to allow doc writer to be polymorphic.
• Added: used prelude constants in trait builder.

Version 0.2.1

• Added MutableModelVisitor trait.

Version 0.2.0

• Major refactor after agreement on the separation of semantic model with Smithy team.
  • Only included the semantic model elements
  • Reworked trait module
  • Made all shape IDs absolute
• Made Builder API create and validate shape IDs.
• Moved UML writer to lib.

Version 0.1.5

• Added UnwelcomeTerms linter.
• API changes for ModelReader and ModelWriter;
  • removed representation method
• Made ActionIssue an std::error::Error.
• Added ModelVisitor to action module.
• Added Model::merge method.

Version 0.1.4

• Completed the NoOrphanedReferences validator.
• Added CorrectTypeReferences validator.
• Added NamingConventions linter.
• Added functions run_linter_actions and run_validation_actions, and removed ValidateAll type.
• Using Regex for identity parsing.
• Moved REPRESENTATION to representation() on ModelReader and ModelWriter traits.

Version 0.1.3

• Made debug and uml Writer implementations features.
• Added module syntax for all string constants.
• Added all defined ShapeIDs to the module prelude.
• Implemented the foundation for actions, also started on validation.
• Implemented Model::resolve_id according to the Smithy spec.

Version 0.1.2

• Updated the model and builder APIs to support JSON and Smithy readers:
  • added the HasMembers trait for a more un-typed API,
• Finished the API documentation.

Version 0.1.1

• Updated the model and builder APIs to be more consistent:
  • documented method patterns, and ensured they were applied,
  • moved from per-type build methods to use Into<T>,
• Added the majority of API documentation.

Version 0.1.0

• First release.
• Initial types for manipulation of Smithy Models, not including selector expressions.
• Initial builder types for fluent construction of models.
• Able to construct the example weather service using the builder API.

TODO

1. Complete the prelude model.
2. More documentation
3. More tests