export const metadata = {
title: 'Architecture',
description:
'Understand the three-layer architecture of rusty_paseto: prelude, generic, and core.',
}
# Architecture
rusty_paseto is organized into three layers, each providing different levels of abstraction. Choose the layer that best fits your needs. {{ className: 'lead' }}
## Layer Overview
The library provides three API layers:
- **Prelude Layer** - High-level, fluent API with PasetoBuilder and PasetoParser
- **Generic Layer** - Claim types, validation utilities
- **Core Layer** - Low-level cryptography with Paseto, Keys, Encryption
---
## Prelude Layer
The **prelude layer** provides the highest-level API with fluent builders and parsers. This is the recommended starting point for most applications.
```rust
use rusty_paseto::prelude::*;
// Building tokens
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(SubjectClaim::from("user_123"))
.set_claim(ExpirationClaim::try_from("2025-01-01T00:00:00Z")?)
.set_claim(CustomClaim::new("role", "admin")?)
.build(&key)?;
// Parsing tokens
let payload = PasetoParser::<V4, Local>::default()
.check_claim(SubjectClaim::from("user_123"))
.parse(&token, &key)?;
```
**Features:**
- Fluent builder pattern
- Automatic claim validation
- Type-safe claim methods
- Strongly-typed result parsing with parse_into
**Enable with:** `features = ["prelude", "v4_local"]`
---
## Generic Layer
The **generic layer** provides claim types and validation without the builder abstraction. Use this when you need more control over token construction.
```rust
use rusty_paseto::generic::*;
// Working with claims directly
let exp = ExpirationClaim::try_from("2025-01-01T00:00:00Z")?;
let sub = SubjectClaim::from("user_123");
// Custom validation
let custom = CustomClaim::new("permissions", vec!["read", "write"])?;
```
**Features:**
- Seven standard PASETO claims
- Custom claim support
- Validation utilities
- Claim error types
**Enable with:** `features = ["generic", "v4_local"]`
---
## Core Layer
The **core layer** provides direct access to PASETO cryptographic operations. Use this for maximum control or when building custom abstractions.
```rust
use rusty_paseto::core::*;
// Direct token creation
let key = PasetoSymmetricKey::<V4, Local>::from(Key::try_new_random()?);
let nonce = PasetoNonce::<V4, Local>::from(&Key::try_new_random()?);
let token = Paseto::<V4, Local>::builder()
.set_payload(Payload::from(r#"{"sub":"user"}"#))
.set_footer(Footer::from("key-id"))
.try_encrypt(&key, &nonce)?;
// Direct token parsing
let payload = Paseto::<V4, Local>::try_decrypt(
&token,
&key,
Footer::from("key-id"),
None,
)?;
```
**Features:**
- Raw cryptographic operations
- Manual nonce handling
- Footer and implicit assertion support
- No automatic claim validation
**Enable with:** `features = ["v4_local"]` (core is always included)
---
## Choosing a Layer
- **Quick start, most applications** - Use Prelude
- **Custom claim types only** - Use Generic
- **Maximum control** - Use Core
- **Building a wrapper library** - Use Core
- **Integration with existing validation** - Use Generic
---
## Layer Dependencies
The layers build on each other: prelude requires generic, which requires core.
- **Prelude** requires Generic and Core
- **Generic** requires Core
- **Core** is always available with any version feature
The feature flags automatically enable required dependencies:
```toml
# This automatically enables generic and core
features = ["prelude", "v4_local"]
```