Struct KitError

Source

pub struct KitError { /* private fields */ }

Expand description

Structured error returned by the portable provider API.

use providers_kit::KitError;
use providers_kit::error::{ErrorKind, ErrorPhase, Operation, ResponseViolation};
let error = KitError::new(
    ErrorKind::InvalidResponse(ResponseViolation::MissingField { field: "modelVersion" }),
    Operation::BatchResults,
    ErrorPhase::Normalize,
).with_row(0);
assert_eq!(error.context().row, Some(0));
assert!(error.to_string().contains("modelVersion"));

Runtime errors are deliberately not serializable. Accepted remote outcomes use RemoteFailure; runtime errors may contain trusted static schema labels and causal Kit failures that must not be reconstructed from untrusted JSON.

use providers_kit::{KitError, error::{ErrorKind, ErrorPhase, Operation}};
let error = KitError::new(ErrorKind::Transport, Operation::Generate, ErrorPhase::RequestSend);
let _ = serde_json::to_string(&error);

Implementations§

Source §

impl KitError

Source

pub fn new(kind: ErrorKind, operation: Operation, phase: ErrorPhase) -> Self

Constructs a classified failure without native details.

use providers_kit::{KitError, error::{ErrorKind, ErrorPhase, Operation}};
let error = KitError::new(ErrorKind::Unsupported, Operation::Embed, ErrorPhase::InputValidation);
assert_eq!(error.kind(), ErrorKind::Unsupported);

Source

pub fn from_remote( failure: RemoteFailure, operation: Operation, phase: ErrorPhase, ) -> Self

Attaches a remote failure to the operation that observed it.

This does not invent an outer HTTP status from an embedded result or stream.

§Examples

use providers_kit::error::{RemoteFailure, NativeErrorDetails, ErrorKind, ClassificationBasis};
let failure = RemoteFailure::new(ErrorKind::NotFound, NativeErrorDetails { message: Some("private detail".into()), ..Default::default() })?;
use providers_kit::error::{KitError, Operation, ErrorPhase};
let error = KitError::from_remote(failure, Operation::FileInfo, ErrorPhase::ReadBody);
assert_eq!(error.kind(), ErrorKind::NotFound);

Source

pub fn classification_basis(&self) -> ClassificationBasis

Returns the basis for classification; caller construction remains explicit.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
let _basis = error.classification_basis();

Source

pub fn remote_failure(&self) -> Option<&RemoteFailure>

Returns an attached remote failure, if one was represented explicitly.

Absence does not establish that the implementation made no service request.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
assert!(error.remote_failure().is_none());

Source

pub fn response_details(&self) -> Option<&ResponseDetails>

Explicitly exposes potentially sensitive observations for a response violation.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
assert!(error.response_details().is_none());

Source

pub fn validation_violation(&self) -> Option<&ValidationViolation>

Returns the safe, detector-assigned local input invariant, when applicable.

use providers_kit::{generation::GenerationConfig, error::ValidationViolation};
let error = GenerationConfig::default().with_temperature(-1.0).unwrap_err();
assert!(matches!(error.validation_violation(), Some(ValidationViolation::OutOfRange {
    field: "generation.temperature", ..
})));

Source

pub fn with_validation_violation(self, violation: ValidationViolation) -> Self

Attaches trusted field/rule labels without exposing rejected caller values.

use providers_kit::{KitError, error::{ErrorKind, ErrorPhase, Operation, ValidationViolation}};
let error = KitError::new(ErrorKind::InvalidInput, Operation::ValidateInput, ErrorPhase::InputValidation)
    .with_validation_violation(ValidationViolation::Empty { field: "messages" });
assert_eq!(error.validation_violation(), Some(&ValidationViolation::Empty { field: "messages" }));

Source

pub fn diagnostics_truncated(&self) -> bool

Reports whether this tree lost diagnostics to string, record, depth, or node bounds.

A tree retains at most eight levels, 32 nodes, and 1 MiB of diagnostic strings. The primary error is retained before its cause subtree and supplementary errors.

use providers_kit::{KitError, error::{ErrorKind, ErrorPhase, NativeErrorDetails, Operation}};
let error = KitError::new(ErrorKind::Transport, Operation::Generate, ErrorPhase::ReadBody)
    .with_native_details(NativeErrorDetails {
        message: Some("x".repeat(65_537)), ..Default::default()
    });
assert!(error.diagnostics_truncated());

Source

pub fn cause(&self) -> Option<&Self>

Returns the cause of this failure, separately from cleanup or diagnostic failures.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
assert!(error.cause().is_none());

Source

pub fn request_target(&self) -> Option<&str>

Explicitly exposes the local requested target; this is not native attribution.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
assert!(error.request_target().is_none());

Source

pub fn correlation_id(&self) -> Option<&str>

Explicitly exposes caller correlation, such as a batch custom ID.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
assert!(error.correlation_id().is_none());

Source

pub fn with_response_details(self, details: ResponseDetails) -> Self

Retains response observations without placing native values in trusted labels.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
let details = providers_kit::error::ResponseDetails::Json { category: providers_kit::error::JsonErrorCategory::Syntax, line: 1, column: 2 };
let error = error.with_response_details(details);
assert!(error.response_details().is_some());

Source

pub fn with_cause(self, cause: Self) -> Self

Retains an actual causal failure. Independent cleanup belongs in supplementary errors.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
let cause = KitError::new(ErrorKind::Timeout, Operation::Generate, ErrorPhase::ReadBody);
let error = error.with_cause(cause);
assert_eq!(error.cause().unwrap().kind(), ErrorKind::Timeout);

Source

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

Retains a bounded local target without asserting that the provider identified it.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
let error = error.with_request_target("private-resource");
assert_eq!(error.request_target(), Some("private-resource"));
assert!(!format!("{error}").contains("private-resource"));

Source

pub fn with_correlation_id(self, id: impl Into<String>) -> Self

Retains bounded caller correlation without treating it as a missing-resource identity.

§Examples

use providers_kit::error::{KitError, ErrorKind, ErrorPhase, Operation};
let error = KitError::new(ErrorKind::Closed, Operation::Generate, ErrorPhase::Lifecycle);
let error = error.with_correlation_id("row-1");
assert_eq!(error.correlation_id(), Some("row-1"));

Source

pub fn kind(&self) -> ErrorKind

Returns the portable classification without interpreting native prose.


assert_eq!(error.kind(), ErrorKind::Transport);

Source

pub fn context(&self) -> &ErrorContext

Returns safe operation, phase and batch row context.


assert_eq!(error.context().operation, Operation::Generate);

Source

pub fn http_status(&self) -> Option<u16>

Returns the actual unsuccessful HTTP status, if one was received.


assert_eq!(error.http_status(), None);

Source

pub fn timeout(&self) -> Option<Duration>

Returns the local deadline that expired, if available.


assert_eq!(error.timeout(), None);

Source

pub fn native_details(&self) -> &NativeErrorDetails

Explicitly exposes potentially sensitive native details; do not log them by default.


assert!(error.native_details().message.is_none());

Source

pub fn supplementary(&self) -> &[KitError]

Returns failures collecting diagnostics or releasing resources after the primary failure.


assert!(error.supplementary().is_empty());

Source

pub fn with_http_status(self, status: u16) -> Self

Attaches an observed HTTP status, never a synthetic status inferred from an event code.


let error = error.with_http_status(503);
assert_eq!(error.http_status(), Some(503));

Source

pub fn with_timeout(self, timeout: Duration) -> Self

Attaches a local deadline; service timeout responses retain their native classification.


let error = error.with_timeout(std::time::Duration::from_secs(10));
assert_eq!(error.timeout(), Some(std::time::Duration::from_secs(10)));

Source

pub fn with_row(self, row: usize) -> Self

Attaches the zero-based logical batch row, excluding blank JSONL lines.


let error = error.with_row(2);
assert_eq!(error.context().row, Some(2));

Source

pub fn with_native_details(self, details: NativeErrorDetails) -> Self

Attaches explicit native details, bounding each string to 64 KiB on UTF-8 boundaries.


let details = providers_kit::error::NativeErrorDetails {
    request_id: Some("sensitive-correlation-id".into()),
    ..Default::default()
};
let error = error.with_native_details(details);
assert!(!error.to_string().contains("sensitive-correlation-id"));

Source

pub fn with_supplementary(self, error: Self) -> Self

Preserves a secondary failure without replacing this failure’s classification or context.


let secondary = KitError::new(ErrorKind::Timeout, Operation::Generate, ErrorPhase::ReadBody);
let error = error.with_supplementary(secondary);
assert_eq!(error.kind(), ErrorKind::Transport);
assert_eq!(error.supplementary()[0].kind(), ErrorKind::Timeout);