Skip to main content

MethodSchema

Struct MethodSchema 

Source
pub struct MethodSchema {
Show 25 fields pub name: String, pub description: String, pub hash: String, pub params: Option<Schema>, pub returns: Schema, pub error: Option<Schema>, pub progress: Option<Schema>, pub cardinality: Cardinality, pub http_method: HttpMethod, pub role: MethodRole, pub deprecation: Option<DeprecationInfo>, pub params_meta: Vec<ParamSchema>, pub credentials: Vec<CredentialFieldDecl>, pub requires_credential: Option<RequiredCredential>, pub auth_posture: Option<AuthPosture>, pub public: bool, pub grant: Option<String>, pub target: Option<String>, pub everywhere: bool, pub long_description: Option<String>, pub held_on: Option<Vec<String>>, pub group: Option<String>, pub answer_by: Option<String>, pub examples: Vec<MethodExample>, pub input: Option<Schema>,
}
Expand description

Schema for a single method exposed by a plugin

Fields§

§name: String

Method name (e.g., “echo”, “check”)

§description: String

Human-readable description of what this method does

§hash: String

Content hash of this method’s schema (for cache invalidation): 16 lowercase hex, SHA-256 of every other field as canonical JSON, so it changes whenever anything a client is generated from changes

§params: Option<Schema>

JSON Schema for the method’s parameters (None if no params)

§returns: Schema

JSON Schema for the method’s item type T — what one success carries.

Always present: every method has a return type. For a Result<T, E> or Progress<T, P> item it is T alone — E and P have fields of their own. MethodSchema::new starts it at the empty schema {} (any value) until MethodSchema::with_returns sets it.

§error: Option<Schema>

JSON Schema for the method’s error type E — what the activation says when it says no (-> Result<T, E>). Absent from the wire when the method is infallible.

§progress: Option<Schema>

JSON Schema for the method’s progress type P (an item of Progress<T, P>), carried by progress frames. Absent from the wire when the method reports no progress.

§cardinality: Cardinality

Whether the method yields one item or many — "one" / "many".

Required on the wire: a schema that does not state its cardinality is not a 0.7 schema, and guessing would reintroduce the disagreement this field exists to end.

§http_method: HttpMethod

HTTP method for REST endpoints (GET, POST, PUT, DELETE, PATCH)

This field is used by the HTTP gateway to determine which HTTP method to use when exposing this method as a REST endpoint. Defaults to POST for backward compatibility.

  • GET: Idempotent read operations (no side effects)
  • POST: Create operations or non-idempotent actions (default)
  • PUT: Replace/update operations (idempotent)
  • DELETE: Remove operations (idempotent)
  • PATCH: Partial update operations
§role: MethodRole

How this method participates in the activation graph.

Added in IR-2. Defaults to MethodRole::Rpc via #[serde(default)] so pre-IR schemas deserialize cleanly.

Populated by the #[plexus::method] / #[child] macros (IR-3).

§deprecation: Option<DeprecationInfo>

If set, this method is deprecated.

Added in IR-2. Defaults to None via #[serde(default)] so pre-IR schemas deserialize cleanly.

Populated by the #[deprecated(...)] attribute on the underlying method (IR-5).

§params_meta: Vec<ParamSchema>

Per-parameter metadata (currently just deprecation).

Added in IR-5. Defaults to an empty vec via #[serde(default)] so pre-IR schemas deserialize cleanly. Only parameters that carry metadata appear in this list — absence means “no metadata” for that parameter, not a bug.

Populated by the #[deprecated(...)] attribute on individual parameters (IR-5).

§credentials: Vec<CredentialFieldDecl>

Credential-bearing fields in this method’s return type.

One entry per #[plexus::credential(...)]-annotated field on the return-type struct/enum, in stable declaration order. Empty when the return type contains no credentials.

Added in AUTHZ-CRED-CORE-3. Defaults to an empty vec via #[serde(default)] so pre-IR schemas deserialize cleanly. The skip_serializing_if = "Vec::is_empty" clause keeps the wire JSON shape unchanged for methods with no credential-bearing fields (back-compat per the ticket’s “Wire-format back-compat” table).

Populated at schema-build time from the CredentialFieldMarker registry emitted by #[derive(Credentials)] (AUTHZ-CRED-MACRO-1).

§requires_credential: Option<RequiredCredential>

What credential this method requires on input (if any).

Derived implicitly from the method’s scope tagging and the credential-graph linkage at schema-build time (per AUTHZ-CRED-CORE-3 §“Implicit derivation”):

  • scope = "..." → RequiredCredential::from_method_scope(scope).
  • public method → None (the absence of this field).
  • target of refresh_via/revoke_via of another credential → RequiredCredential::from_refresh_revoke_target(kind, scopes).

Added in AUTHZ-CRED-CORE-3. Defaults to None via #[serde(default)] so pre-IR schemas deserialize cleanly. The skip_serializing_if = "Option::is_none" clause keeps the wire JSON shape unchanged for public methods and methods with no scope-derived requirement.

§auth_posture: Option<AuthPosture>

Declared auth posture of the activation this method belongs to.

Populated by #[plexus_macros::activation(auth = "...")] (R-1) — stamped onto every RPC method of the activation. None means the activation never declared a posture (pre-R-1 emissions and posture-silent activations are byte-identical on the wire).

Added in R-2 (joint AP-1). Defaults to None via #[serde(default)] so pre-R IRs decode cleanly; skip_serializing_if keeps the wire shape unchanged when unset.

§public: bool

Whether this method is explicitly public — exempt from the default-deny gate (AUTHZ-CORE-2’s #[plexus::method(public)]).

public and a populated requires_credential are mutually exclusive by construction: the macro rejects public + scope = "..." at compile time.

Added in R-2. Defaults to false via #[serde(default)] so pre-R IRs decode cleanly; skip_serializing_if keeps the wire shape unchanged for non-public methods (i.e., every pre-R method).

§grant: Option<String>

AUTH-3: the grant this method is — <activation>.<method>, inherent (AUTH-1: “every method should be its own grant”). The macro emits it for every method; None only on a hand-built or pre-AUTH schema, and a gate then takes the method’s dotted path.

Optional on the wire (serde(default), skipped when unset) so older schemas and clients parse unchanged.

§target: Option<String>

AUTH-3: the param that locates what this call acts on (#[plexus_macros::method(target = "id")]). A gate resolves its value to the scopes it lives in and asks for the grant there; a method without one is allowed where the grant is held anywhere and answers only from there.

§everywhere: bool

KEEL-31: the method acts on the whole service (#[plexus_macros::method(everywhere)]): it names no target because its target is everything — a key rotated, a process spawned, a peer connected. A gate admits it only where its grant is held on *, within every ceiling layer; a role held on some scope is not enough. Never with public or target.

Optional on the wire (serde(default), skipped when false) so a method without it, and every older schema and client, is unchanged.

§long_description: Option<String>

AUTH-3: the method’s /// doc comment, when it says more than description (the macro used to drop it whenever description = "..." was given).

§held_on: Option<Vec<String>>

AUTH-4: in a caller’s view of a gated hub, where the caller holds this method’s grant (["MENGER"], ["*"]), within its session’s ceiling. Absent outside a caller’s view (and on a public method the caller holds nowhere).

§group: Option<String>

SYNAPSE-13: the method’s group in a listing ("read", "write", …) — one group, like an OpenAPI operation’s first tag. Clients list the methods of a group together and alphabetically within it.

Optional on the wire (serde(default), skipped when unset) so older schemas and clients parse unchanged.

§answer_by: Option<String>

BIDIR-8: who may answer a question this method asks mid-call (#[method(answer_by = "person" | "grant:<g>")]; BIDIR-1 answerer). Absent for the default, caller — the call’s own connection — so a method without the attribute is byte-identical.

§examples: Vec<MethodExample>

SYNAPSE-13: worked calls of this method, each its params object and a note saying what it does — OpenAPI’s examples. A client renders them as command lines (synapse … --id MENGER-40 --status Coding).

Optional on the wire (serde(default), skipped when empty).

§input: Option<Schema>

SYNAPSE-CC-9: reserved for BIDIR-6 — the JSON Schema of the items a client streams in to this method (Input<T>). Always None until BIDIR-6 fills it; absent from the wire while None, so a schema without it is byte-identical to 0.6.1’s.

Implementations§

Source§

impl MethodSchema

Source

pub fn new( name: impl Into<String>, description: impl Into<String>, hash: impl Into<String>, ) -> Self

Create a new method schema with name, description, and hash

RETURNS-10: a method’s hash is its schema’s content_hash. Build the schema with hash empty and finish with with_content_hash, as the code #[plexus_macros::activation] emits does.

Starts as an infallible, progress-free Cardinality::One method whose returns is the empty schema {} (any value); the builders with_returns, with_error, with_progress and with_cardinality state the real contract.

Source

pub fn auto_schema() -> Self

SYNAPSE-CC-9: the entry of the schema method every activation answers — params {method?: string} (SchemaParams) and returns SchemaResult (this PluginSchema, or one MethodSchema when called with {"method": …}; RETURNS-26). The macro adds the activation’s grant.

Source

pub fn is_auto_schema(&self) -> bool

Is this the schema entry every activation’s macro adds (auto_schema)?

RETURNS-36: known by what every 0.8.x build writes alike, never by a hash recomputed with this build (review #11): named schema, an Rpc of one item with no error and no progress, its params {method?} alone and its returns titled SchemaResult — or main’s fixed marker hash, "auto_schema", from a peer still sending it. A method an author named schema with other params or another return is not it.

Source

pub fn with_input(self, input: Schema) -> Self

SYNAPSE-CC-9: reserved for BIDIR-6 — the schema of the items a client streams in.

Source

pub fn content_hash(&self) -> String

RETURNS-10: this method’s content hash — 16 lowercase hex.

The schema as it serializes, without its own hash field, written as canonical JSON (keys sorted, no whitespace, arrays in order) and hashed with hash16 (SHA-256, first 8 bytes). It covers everything a client is generated from — name, description, params, returns / error / progress down to every nested field, variant and doc comment, cardinality, role, deprecation, credentials, auth posture — so one hash means one schema. A consumer recomputes it from the wire, e.g. in Python:

m = dict(method); del m["hash"]
sha256(json.dumps(m, sort_keys=True, separators=(",", ":"),
                  ensure_ascii=False).encode()).hexdigest()[:16]

Costs one serialization and one SHA-256 pass over the schema: compute it once where schemas are cached, not per plugin_schema() call.

Source

pub fn with_content_hash(self) -> Self

RETURNS-10: set hash to content_hash — the last step of building a schema (a builder applied after it would change the schema without moving its hash).

Source

pub fn with_params(self, params: Schema) -> Self

Add parameter schema

Source

pub fn with_returns(self, returns: Schema) -> Self

Set the schema of the method’s item type T.

Source

pub fn with_error(self, error: Schema) -> Self

Set the schema of the method’s error type E (a fallible method, Result<T, E>).

Source

pub fn with_progress(self, progress: Schema) -> Self

Set the schema of the method’s progress type P (an item of Progress<T, P>).

Source

pub fn with_cardinality(self, cardinality: Cardinality) -> Self

Set whether the method yields one item or many.

MethodSchema::new starts at Cardinality::One.

Source

pub fn with_http_method(self, http_method: HttpMethod) -> Self

Set the HTTP method for REST endpoints

Defaults to POST for backward compatibility.

§Guidelines
  • GET: Idempotent read operations with no side effects
  • POST: Create operations or non-idempotent actions
  • PUT: Replace/update operations (idempotent)
  • DELETE: Remove operations (idempotent)
  • PATCH: Partial update operations
Source

pub fn with_role(self, role: MethodRole) -> Self

Set this method’s role in the activation graph.

Added in IR-2. Defaults to MethodRole::Rpc.

Source

pub fn with_deprecation(self, info: DeprecationInfo) -> Self

Mark this method as deprecated.

Added in IR-2. Populates the deprecation field with the provided DeprecationInfo.

Source

pub fn with_params_meta(self, entries: Vec<ParamSchema>) -> Self

Attach per-parameter metadata for this method’s parameters.

Added in IR-5. Only parameters that carry metadata (e.g. a #[deprecated] annotation) need appear in entries; absence means “no metadata” for a given parameter. The consumer correlates entries against self.params by matching ParamSchema.name against the properties map of the JSON Schema.

Source

pub fn with_credentials(self, credentials: Vec<CredentialFieldDecl>) -> Self

Attach the credential-field projection for this method’s return type.

Added in AUTHZ-CRED-CORE-3. The build-path supplies one CredentialFieldDecl per #[plexus::credential(...)]-annotated field in the return type, in stable declaration order. Absence (the default empty vec) means the return type carries no credentials.

The constructor CredentialFieldDecl::from_marker composes one entry from a CredentialFieldMarker (emitted by the #[derive(Credentials)] macro) plus the runtime-known issuer.

Source

pub fn with_requires_credential(self, req: RequiredCredential) -> Self

Attach the implicit-derived requires_credential filter for this method.

Added in AUTHZ-CRED-CORE-3. The build-path supplies a RequiredCredential derived from either (a) the method’s scope attribute or (b) the method’s appearance as a refresh_via / revoke_via target of some other credential in the schema. Public methods leave this field as None (the default).

RequiredCredential::from_method_scope and RequiredCredential::from_refresh_revoke_target are the two derivation entry points.

Source

pub fn with_auth_posture(self, posture: AuthPosture) -> Self

Stamp the activation-declared auth posture onto this method.

Added in R-2 (joint AP-1). Populated by the #[plexus_macros:: activation(auth = "...")] emission (R-1); only explicitly declared postures are stamped — activations that never declare auth = "..." leave this None so their wire output is byte-identical to pre-R emissions.

Source

pub fn with_public(self, public: bool) -> Self

Mark this method as explicitly public (AUTHZ-CORE-2’s #[plexus::method(public)]) — exempt from the default-deny gate.

Added in R-2. Populated by the macro emission (R-1); the macro rejects public + scope = "..." at compile time, so a public method never carries a scope-derived requires_credential.

Source

pub fn with_grant(self, grant: impl Into<String>) -> Self

AUTH-3: set the method’s grant (<activation>.<method>).

Source

pub fn with_target(self, target: impl Into<String>) -> Self

AUTH-3: name the param that locates what this call acts on.

Source

pub fn with_everywhere(self, everywhere: bool) -> Self

KEEL-31: mark the method as acting on the whole service — its grant is needed on * (MethodSchema::everywhere).

Source

pub fn with_long_description(self, long_description: impl Into<String>) -> Self

AUTH-3: the doc comment’s fuller text.

Source

pub fn with_answer_by(self, answer_by: impl Into<String>) -> Self

BIDIR-8: who may answer a question this method asks mid-call, as #[method(answer_by = "…")] declares it (person, grant:<g>); the default (caller) is left unset.

Source

pub fn answerer(&self) -> Result<Answerer, String>

BIDIR-8: the method’s Answerer — answer_by read, absent the default (caller). A spelling the macro would refuse is an error, never a wider answerer.

Source

pub fn with_group(self, group: impl Into<String>) -> Self

SYNAPSE-13: put this method in a listing group ("read", "write").

Source

pub fn with_example(self, example: MethodExample) -> Self

SYNAPSE-13: add a worked call of this method.

Source

pub fn with_param_values<I, S>(self, param: &str, values: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

SYNAPSE-13: say which values param is meant to take, as X_PLEXUS_VALUES on its property in params — a hint, never enforced. A param the schema does not have is left alone.

Source

pub fn param_values(&self, param: &str) -> Option<Vec<String>>

SYNAPSE-13: the values param is meant to take, when its property says them (X_PLEXUS_VALUES).

Source

pub fn grant_or(&self, activation: &str) -> String

AUTH-2: the grant a gate asks for this method under activation: the schema’s own grant, else <activation>.<name>.

Source

pub fn fill_site_hint(&mut self, site: &AttachmentSite)

CA-1: fill requires_credential.site_hint with the hub-derived attach site when the method carries a requirement that lacks one. Methods without a requires_credential are untouched — derivation never creates a requirement (AUTHZ-CRED-CORE-3’s implicit-only contract).

Trait Implementations§

Source§

impl Clone for MethodSchema

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for MethodSchema

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<'de> Deserialize<'de> for MethodSchema

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl JsonSchema for MethodSchema

Source§

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema. Read more
Source§

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type. Read more
Source§

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type. Read more
Source§

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword. Read more
Source§

impl Serialize for MethodSchema

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> MaybeSend for T
where T: Send,

Source§

impl<T> MaybeSendSync for T
where T: Send + Sync,

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> SettingValue for T
where T: Serialize + DeserializeOwned + JsonSchema + Clone + Send + Sync + 'static,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more