pub struct MethodSchema {Show 26 fields
pub name: String,
pub description: String,
pub hash: String,
pub params: Option<Schema>,
pub returns: Option<Schema>,
pub streaming: bool,
pub bidirectional: bool,
pub http_method: HttpMethod,
pub request_type: Option<Schema>,
pub response_type: Option<Schema>,
pub role: MethodRole,
pub deprecation: Option<DeprecationInfo>,
pub return_shape: Option<ReturnShape>,
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 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: StringMethod name (e.g., “echo”, “check”)
description: StringHuman-readable description of what this method does
hash: StringContent hash of the method definition (for cache invalidation) Generated by hashing the method signature within hub-macro
params: Option<Schema>JSON Schema for the method’s parameters (None if no params)
returns: Option<Schema>JSON Schema for the method’s return type (None if not specified)
streaming: boolWhether this method streams multiple events (true) or returns a single result (false)
streaming: true→ returnsAsyncGenerator<T>(multiple events)streaming: false→ returnsPromise<T>(single event, collected)
All methods use the same streaming protocol under the hood, but this flag tells clients how to present the result.
bidirectional: boolWhether this method supports bidirectional communication
When true, the server can send requests to the client during method execution and wait for responses (e.g., confirmations, prompts, selections).
http_method: HttpMethodHTTP 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
request_type: Option<Schema>JSON Schema for the request type sent from server to client
Only relevant when bidirectional: true. Describes the structure of
requests the server may send during method execution.
response_type: Option<Schema>JSON Schema for the response type sent from client to server
Only relevant when bidirectional: true. Describes the structure of
responses the client should send in reply to server requests.
role: MethodRoleHow 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).
return_shape: Option<ReturnShape>Structural shape of the method’s return type (e.g., Option, Vec,
Stream).
Orthogonal to returns, which holds the fine-grained JSON Schema of
the inner type. Added in IR-2 as an optional, additive field. None
means “not populated” (the wire format supports pre-IR schemas that
omit this field entirely).
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).publicmethod →None(the absence of this field).- target of
refresh_via/revoke_viaof 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: boolWhether 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.
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
impl MethodSchema
Sourcepub fn new(
name: impl Into<String>,
description: impl Into<String>,
hash: impl Into<String>,
) -> Self
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
The hash should be computed from the method definition string within the hub-macro at compile time.
Sourcepub fn auto_schema() -> Self
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.
Sourcepub fn with_input(self, input: Schema) -> Self
pub fn with_input(self, input: Schema) -> Self
SYNAPSE-CC-9: reserved for BIDIR-6 — the schema of the items a client streams in.
Sourcepub fn with_params(self, params: Schema) -> Self
pub fn with_params(self, params: Schema) -> Self
Add parameter schema
Sourcepub fn with_returns(self, returns: Schema) -> Self
pub fn with_returns(self, returns: Schema) -> Self
Add return type schema
Sourcepub fn with_streaming(self, streaming: bool) -> Self
pub fn with_streaming(self, streaming: bool) -> Self
Set the streaming flag
true→ method streams multiple events (useAsyncGenerator<T>)false→ method returns single result (usePromise<T>)
Sourcepub fn with_http_method(self, http_method: HttpMethod) -> Self
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
Sourcepub fn with_bidirectional(self, bidirectional: bool) -> Self
pub fn with_bidirectional(self, bidirectional: bool) -> Self
Set whether this method supports bidirectional communication
When true, the server can send requests to the client during method execution and wait for responses.
Sourcepub fn with_request_type(self, schema: Schema) -> Self
pub fn with_request_type(self, schema: Schema) -> Self
Set the JSON Schema for server-to-client request types
Only relevant when bidirectional: true. Use schema_for!(YourRequestType)
to generate the schema.
Sourcepub fn with_response_type(self, schema: Schema) -> Self
pub fn with_response_type(self, schema: Schema) -> Self
Set the JSON Schema for client-to-server response types
Only relevant when bidirectional: true. Use schema_for!(YourResponseType)
to generate the schema.
Sourcepub fn with_standard_bidirectional(self) -> Self
pub fn with_standard_bidirectional(self) -> Self
Configure method for standard bidirectional communication
Sets bidirectional: true and configures request/response types to use
StandardRequest and StandardResponse, which support common UI patterns
like confirmations, prompts, and selections.
Sourcepub fn with_role(self, role: MethodRole) -> Self
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.
Sourcepub fn with_deprecation(self, info: DeprecationInfo) -> Self
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.
Sourcepub fn with_return_shape(self, shape: ReturnShape) -> Self
pub fn with_return_shape(self, shape: ReturnShape) -> Self
Set the structural shape of this method’s return type.
Added in IR-2. Orthogonal to with_returns, which sets the fine-grained
JSON Schema.
Sourcepub fn with_params_meta(self, entries: Vec<ParamSchema>) -> Self
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.
Sourcepub fn with_credentials(self, credentials: Vec<CredentialFieldDecl>) -> Self
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.
Sourcepub fn with_requires_credential(self, req: RequiredCredential) -> Self
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.
Sourcepub fn with_auth_posture(self, posture: AuthPosture) -> Self
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.
Sourcepub fn with_public(self, public: bool) -> Self
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.
Sourcepub fn with_grant(self, grant: impl Into<String>) -> Self
pub fn with_grant(self, grant: impl Into<String>) -> Self
AUTH-3: set the method’s grant (<activation>.<method>).
Sourcepub fn with_target(self, target: impl Into<String>) -> Self
pub fn with_target(self, target: impl Into<String>) -> Self
AUTH-3: name the param that locates what this call acts on.
Sourcepub fn with_long_description(self, long_description: impl Into<String>) -> Self
pub fn with_long_description(self, long_description: impl Into<String>) -> Self
AUTH-3: the doc comment’s fuller text.
Sourcepub fn with_answer_by(self, answer_by: impl Into<String>) -> Self
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.
Sourcepub fn with_group(self, group: impl Into<String>) -> Self
pub fn with_group(self, group: impl Into<String>) -> Self
SYNAPSE-13: put this method in a listing group ("read", "write").
Sourcepub fn with_example(self, example: MethodExample) -> Self
pub fn with_example(self, example: MethodExample) -> Self
SYNAPSE-13: add a worked call of this method.
Sourcepub fn with_param_values<I, S>(self, param: &str, values: I) -> Self
pub fn with_param_values<I, S>(self, param: &str, values: I) -> Self
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.
Sourcepub fn param_values(&self, param: &str) -> Option<Vec<String>>
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).
Sourcepub fn grant_or(&self, activation: &str) -> String
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>.
Sourcepub fn fill_site_hint(&mut self, site: &AttachmentSite)
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
impl Clone for MethodSchema
Source§impl Debug for MethodSchema
impl Debug for MethodSchema
Source§impl<'de> Deserialize<'de> for MethodSchema
impl<'de> Deserialize<'de> for MethodSchema
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Source§impl JsonSchema for MethodSchema
impl JsonSchema for MethodSchema
Source§fn schema_id() -> Cow<'static, str>
fn schema_id() -> Cow<'static, str>
Source§fn json_schema(generator: &mut SchemaGenerator) -> Schema
fn json_schema(generator: &mut SchemaGenerator) -> Schema
Source§fn inline_schema() -> bool
fn inline_schema() -> bool
$ref keyword. Read more