Rule-Engine: Experimental Context Traits

[skmcgrail]

Adds support for new AWS context traits clientContextParams, staticContextParams, and contextParam.

• smithy.rules#clientContextParams is a trait that may be applied to a Service shape. It is used to indicate that the named context parameters that should be configurable on a top-level API client. The trait is a mapping of the context parameter name to their definition containing the Smithy shape type used to represent it, documentation string for the client, and context usages. Valid usages are endpoint, and valid shape types supported are string and boolean.

• smithy.rules#staticContextParams is a trait that may be applied to an Operation shape. It is a mapping of context parameter names to their definition containing the static value to be configured for the parameter, and context usages. Valid usages are endpoint.

• smithy.rules#contextParam is a trait that may be applied to a Member shape. The trait indicates the target context parameter name that the member's value should be bound to as, as well as the context usages. Valid usages are endpoint. Per specification this trait will only be supported on the top-level operation input shape.

• smithy.rules#endpointRuleSet is a trait that is used to embed a rule-set document.

Example Model

$version: "1.0"

namespace ns.foo

use smithy.rules#clientContextParams
use smithy.rules#staticContextParams
use smithy.rules#contextParam
use smithy.rules#endpointRuleSet

@clientContextParams(
    stringParam: {type: "string", documentation: "a client string parameter"},
    booleanParam: {type: "boolean", documentation: "a client boolean parameter"}
)
service ExampleService {
    version: "2022-01-01",
    operations: [GetThing]
}

apply ExampleService @endpointRuleSet({
    version: "1.0",
    serviceId: "example",
    parameters: {
        stringParam: {type: "string"},
        booleanParam: {type: "boolean"}
    },
    rules: []
})

@readonly
@staticContextParams(
    stringParam: {value: "some value"},
    booleanParam: {value: true}
)
operation GetThing {
    input: GetThingInput
}

@input
structure GetThingInput {
    fizz: String,

    @contextParam(name: "stringParam")
    buzz: String,
}

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[mtdowling]

I’m tempted to make this part of Smithy core rather than something AWS-specific. Seems simple enough so far, but I guess the decision hinges on the associated endpoint rules configuration and whether they can be generic enough too.

[rcoh]

My recommendation would be to have this be in Smithy core—this would influence code generation of endpoint parameter structures / configuration wiring.

For the rules, I'd put them in something like smithy.experimental.endpoints—I think it's too early to move them into core.

You might imagine that a customer uses the endpoint parameters but than hand-writes a simple endpoint resolver instead of relying on rules.

[skmcgrail]

Updated this PR with the latest trait designs & feedback. This should be good for another review pass now.

[skmcgrail]

Implemented all feedback, except for the final documentation pieces within the model.

[skmcgrail]

Rebased commits on top of 1.22.0.

[skmcgrail]

Good for follow-up review.