axiam-sdk 1.2.2

Official Rust client SDK for AXIAM IAM
Documentation
// @generated by tools/gen_management.py from management-registry.json and
// openapi.json. DO NOT EDIT -- your changes will be overwritten. Regenerate
// with `tools/gen_management.py`; CI verifies the committed output is current.

//! The `ssf` management namespace (CONTRACT §27.1).
//!
//! A tenant's Shared Signals Framework streams (CONTRACT §32): which receiver
//! -- an OAuth2 client of the tenant -- receives which CAEP and RISC security
//! events, as SETs pushed to its endpoint or polled. The receiver's own
//! protocol (transmitter metadata, the SSF stream management API, polling) is
//! not in this registry.

#![allow(clippy::too_many_arguments)]

use uuid::Uuid;

use crate::AxiamError;
use crate::client::AxiamClient;
use crate::management::models;
use crate::management::page::{Page, PageRequest, collect_pages};
use crate::management::request::{Call, Verb};
use crate::management::scope::Scope;

/// The `ssf` namespace handle.
///
/// A tenant's Shared Signals Framework streams (CONTRACT §32): which receiver
/// -- an OAuth2 client of the tenant -- receives which CAEP and RISC security
/// events, as SETs pushed to its endpoint or polled. The receiver's own
/// protocol (transmitter metadata, the SSF stream management API, polling) is
/// not in this registry.
///
/// Acquiring one performs no I/O and allocates nothing meaningful (§27.2 rule
/// 1); it borrows the client and cannot outlive it.
#[derive(Clone, Copy)]
pub struct Ssf<'c> {
    pub(crate) client: &'c AxiamClient,
    pub(crate) scope: Scope,
}

impl std::fmt::Debug for Ssf<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Ssf").field("scope", &self.scope).finish()
    }
}

impl<'c> Ssf<'c> {
    pub(crate) fn new(client: &'c AxiamClient) -> Self {
        Self {
            client,
            scope: Scope::default(),
        }
    }

    /// Address a different tenant than the client's own.
    ///
    /// §27.4 rule 3: the client's `tenant_id` is the default.
    #[must_use]
    pub fn for_tenant(mut self, tenant_id: Uuid) -> Self {
        self.scope.tenant_id = Some(tenant_id);
        self
    }

    /// `GET /api/v1/tenants/{tenant_id}/ssf/streams`
    pub async fn list_streams(
        &self,
        page: PageRequest,
    ) -> Result<Page<models::SsfStream>, AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "ssf.list_streams")?;
        let query = page.query();
        let call = Call {
            operation: "ssf.list_streams",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/ssf/streams",
            path: format!("/api/v1/tenants/{tenant_id}/ssf/streams"),
            query: &query,
        };
        self.client
            .management_send::<_, Page<models::SsfStream>>(call, None::<&()>)
            .await
    }

    /// Walk `ssf.list_streams` to exhaustion, concatenating every page.
    ///
    /// The auto-paging form §27.4 rule 4 requires. It stops on an empty page even
    /// if `total` disagrees, so a misreporting server costs one wasted request
    /// rather than an unbounded loop.
    pub async fn list_streams_all(
        &self,
        start: PageRequest,
    ) -> Result<Vec<models::SsfStream>, AxiamError> {
        collect_pages(start, |p| self.list_streams(p)).await
    }

    /// `POST /api/v1/tenants/{tenant_id}/ssf/streams`
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn create_stream(
        &self,
        body: &models::SsfStreamInput,
    ) -> Result<models::SsfStream, AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "ssf.create_stream")?;
        let body = models::SsfStreamInputWire::from(body);
        let body = &body;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "ssf.create_stream",
            verb: Verb::Post,
            path_template: "/api/v1/tenants/{tenant_id}/ssf/streams",
            path: format!("/api/v1/tenants/{tenant_id}/ssf/streams"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SsfStream>(call, Some(body))
            .await
    }

    /// `GET /api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}`
    pub async fn get_stream(&self, stream_id: Uuid) -> Result<models::SsfStream, AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "ssf.get_stream")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "ssf.get_stream",
            verb: Verb::Get,
            path_template: "/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}",
            path: format!("/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SsfStream>(call, None::<&()>)
            .await
    }

    /// `PUT /api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}`
    /// **This is a replacement, not a patch** (§27.4 rule 5). Its required fields
    /// must all be given, and what you do not carry over from a prior read is not
    /// preserved: an optional member left `None` is omitted, and the server
    /// applies that member's default rather than keeping the stored value --
    /// unless a note below says otherwise. Read first, change the field you mean,
    /// send the whole thing back.
    ///
    /// **`events_requested` has three meanings on an update** (§32.2, contract
    /// 1.62), and they must be kept apart. Left `None` (absent) it **resets** the
    /// stream to *every* event of `events_allowed`, as on create -- widening a
    /// narrowing the receiver made, so AXIAM then sends the receiver more events
    /// about the tenant's users than it asked for. An explicitly **empty list**
    /// (`Some` of an empty vector) is stored as the receiver's "none": it does
    /// not widen, and the stream carries nothing. A list of event types is stored
    /// as given and refused (`400`) if any is outside `events_allowed`. A raw API
    /// client is bound by the same meaning: an `events_requested` left out of the
    /// `PUT` resets the stream. The other omitted optional members take their
    /// defaults on an update too. To edit a stream you read, start from
    /// `SsfStreamInput::from_stream_with(&stream, changes)`, which sends
    /// `events_requested` and `expected_updated_at` as read and cuts
    /// `events_requested` to a lowered `events_allowed`. An omitted optional
    /// member takes its default (§32.2) -- **except `authorization_header`, which
    /// absent keeps the stored one** -- unless the update moves `endpoint_url` to
    /// another scheme, host or port while a header is stored: then it must carry
    /// `authorization_header` again or `clear_authorization_header: true`, else
    /// `400` (§32.3 rule 5). An update overtaken by the receiver's own write is
    /// `409`: read the stream again.
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn update_stream(
        &self,
        stream_id: Uuid,
        body: &models::SsfStreamInput,
    ) -> Result<models::SsfStream, AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "ssf.update_stream")?;
        let body = models::SsfStreamInputWire::from(body);
        let body = &body;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "ssf.update_stream",
            verb: Verb::Put,
            path_template: "/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}",
            path: format!("/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}"),
            query: &query,
        };
        self.client
            .management_send::<_, models::SsfStream>(call, Some(body))
            .await
    }

    /// `DELETE /api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}`
    /// Not retried on failure (§27.4 rule 8): every write on this surface is
    /// issued exactly once, including the ones that look idempotent.
    pub async fn delete_stream(&self, stream_id: Uuid) -> Result<(), AxiamError> {
        let tenant_id = self.scope.tenant(self.client, "ssf.delete_stream")?;
        let query: Vec<(&'static str, String)> = Vec::new();
        let call = Call {
            operation: "ssf.delete_stream",
            verb: Verb::Delete,
            path_template: "/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}",
            path: format!("/api/v1/tenants/{tenant_id}/ssf/streams/{stream_id}"),
            query: &query,
        };
        self.client
            .management_send_no_content(call, None::<&()>)
            .await
    }
}