aws_smithy_schema/schema/
payload_hint.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6/// Whether a structure has an `@httpPayload` member that supplies its own body
7/// framing, ex: a member carrying `@httpPayload` whose target is a
8/// `structure` or a `union`.
9///
10/// # Why this is a hint and not a fact
11///
12/// The HTTP binding protocol needs this answer on every request, and deriving
13/// it means scanning the input schema's members. Codegen already knows the
14/// answer, so it records it here and the runtime reads it instead of scanning.
15///
16/// [`Unknown`](PayloadHint::Unknown) is the default, and the runtime falls back
17/// to scanning when it sees it. That fallback is permanent, not
18/// transitional. Two callers rely on it:
19///
20/// - schemas constructed by hand or materialized at runtime, which have no
21///   codegen step to set the hint;
22/// - generated crates produced *before* codegen began emitting the hint, which
23///   Cargo permits to link against a newer `aws-smithy-schema` within the same
24///   major version.
25///
26/// So this value must never become load-bearing for correctness. Anything that
27/// consumes it has to produce identical output for `Unknown` by deriving the
28/// answer itself.
29///
30/// # Why the framing question rather than the payload's shape
31///
32/// The variants deliberately answer "does a payload member frame the body?"
33/// rather than describing the payload's type. `@httpPayload` may also target a
34/// `blob`, `string`, or `document`, and those are not grouped together by the
35/// runtime: blob and string payloads bypass the codec entirely (their bytes
36/// become the body verbatim), while a document payload is written through the
37/// codec. A variant named for one of those groupings would either be wrong or
38/// would have to change meaning if a consumer for the distinction appeared.
39///
40/// The enum is `#[non_exhaustive]`, so a finer classification can be added
41/// later without a breaking change.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
43#[non_exhaustive]
44pub enum PayloadHint {
45    /// Not recorded. Consumers must derive the answer themselves.
46    ///
47    /// This is the default for every schema, including every hand-constructed
48    /// one.
49    #[default]
50    Unknown,
51
52    /// No member carries `@httpPayload` targeting a `structure` or `union`.
53    ///
54    /// Body framing, if any, comes from the codec.
55    NoStructPayload,
56
57    /// A member carries `@httpPayload` targeting a `structure` or `union`.
58    ///
59    /// That member writes its own framing, so the codec must not add
60    /// top-level framing around it.
61    StructPayload,
62}
aws_smithy_schema/schema/payload_hint.rs

aws_smithy_schema/schema/
payload_hint.rs
