Struct Guard 

pub struct Guard { /* private fields */ }

请求守卫：一个可跨请求共享、可跨线程克隆的加密句柄。

构造之后的一切加解密都经由它转发到 EncryptionManager；克隆只是 Arc 引用计数递增，不含任何密钥拷贝。

Implementations

impl Guard

pub fn new(manager: EncryptionManager) -> Self

从一个已经建好的 Manager 构造。

pub fn from_master_key( master_key: &[u8], default_identifier: &str, ) -> Result<Self>

从 32 字节主密钥构造（内部走 crate::factory::EncryptionManagerFactory）。

构造时即完成全部校验（主密钥长度、默认算法是否注册），配置错了就在启动时炸。

pub fn from_env() -> Result<Self>

从进程环境变量构造。

读取 ENCRYPTION_MASTER_KEY（必需）与 ENCRYPTION_ALGORITHM（可选， 缺省 aes-256-gcm）。主密钥值的格式见 Self::from_env_with。

pub fn from_env_with<F: Fn(&str) -> Option<String>>(lookup: F) -> Result<Self>

从可注入的查找函数构造：测试与自定义配置源（KMS / 配置中心）走这里。

主密钥取值 lookup("ENCRYPTION_MASTER_KEY")，格式为显式前缀 hex:<十六进制> / base64:<Base64>；无前缀时自动判定：去掉首尾空白后 恰为 64 个十六进制字符按 hex，否则按 Base64。解码后必须恰好 32 字节， 否则 Error::InvalidMasterKey；算法名未注册时冒泡 Error::UnknownIdentifier。

use encryption::guard::Guard;

// 假 lookup：真实场景用 std::env::var 或配置中心
let lookup = |key: &str| match key {
    "ENCRYPTION_MASTER_KEY" => Some("00".repeat(32)), // 裸 hex（64 位）
    _ => None,
};

let guard = Guard::from_env_with(lookup)?;
assert_eq!(guard.manager().default_identifier(), "aes-256-gcm");

let blob = guard.encrypt("13800138000".as_bytes())?;
assert_eq!(guard.decrypt(&blob)?, "13800138000".as_bytes());

pub fn manager(&self) -> &EncryptionManager

共享的 Manager。总是存在。

pub fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>>

用默认算法加密。

pub fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>>

用默认算法解密。

pub fn encrypt_with( &self, identifier: &str, plaintext: &[u8], ) -> Result<Vec<u8>>

用指定算法加密。

pub fn decrypt_with( &self, identifier: &str, ciphertext: &[u8], ) -> Result<Vec<u8>>

用指定算法解密。

pub fn identifiers(&self) -> Vec<&str>

已注册算法标识（健康检查 / 日志用）。

Trait Implementations

impl Clone for Guard

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Guard

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

Formats the value using the given formatter.

impl<'ex> Extractible<'ex> for Guard

fn metadata() -> &'static Metadata

Metadata for this extractible type.

async fn extract( _req: &'ex mut Request, depot: &'ex mut Depot, ) -> Result<Self, GuardNotConfigured>

Extracts data from a request.

fn extract_with_arg( req: &'ex mut Request, depot: &'ex mut Depot, _arg: &str, ) -> impl Future<Output = Result<Self, impl Writer + Send + Debug + 'static>> + Send

where Self: Sized,

Extract data from a request with an argument. This function is used internally by macros.

impl FromRequest for Guard

type Future = Ready<Result<Guard, <Guard as FromRequest>::Error>>

纯同步取值，不需要装箱 —— 拷贝一次 Arc 而已。

type Error = Error

The associated error which can be returned.

fn from_request(req: &HttpRequest, _payload: &mut Payload) -> Self::Future

Create a Self from request parts asynchronously.

fn extract(req: &HttpRequest) -> Self::Future

Create a Self from request head asynchronously.

impl<'a> FromRequest<'a> for Guard

async fn from_request(req: &'a Request, _body: &mut RequestBody) -> Result<Self>

Extract from request head and body.

fn from_request_without_body( req: &'a Request, ) -> impl Future<Output = Result<Self, Error>> + Send

Extract from request head.

impl<'r> FromRequest<'r> for Guard

type Error = GuardNotConfigured

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( request: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

impl<S> FromRequestParts<S> for Guard

where S: Guarded + Send + Sync,

async fn from_request_parts( _parts: &mut Parts, state: &S, ) -> Result<Self, Self::Rejection>

从应用状态取守卫，克隆一份交给处理器。

克隆的是 Arc，不是密钥材料 —— 每请求的成本就是一次引用计数递增。

type Rejection = !

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

impl Guarded for Guard

fn guard(&self) -> &Guard

取出守卫。永远成功 —— 取不到说明状态装配错了，那是编译期该发现的事。