ferro_rs/
lib.rs

1//! Ferro — a full-stack web framework for Rust.
2//!
3//! Provides routing, database access, validation, authentication, queues,
4//! events, notifications, broadcasting, storage, caching, and Inertia.js
5//! integration in a single cohesive package.
6#![warn(missing_docs)]
7
8/// API key management and OpenAPI specification generation.
9pub mod api;
10pub mod app;
11pub mod auth;
12pub mod authorization;
13pub mod broadcast;
14pub mod cache;
15pub mod config;
16pub mod container;
17pub mod csrf;
18pub mod database;
19pub mod debug;
20pub mod error;
21pub mod hashing;
22/// HTTP request, response, cookie, and resource types.
23pub mod http;
24#[cfg(feature = "inertia")]
25pub mod inertia;
26#[cfg(feature = "json-ui")]
27pub mod json_ui;
28pub mod lang;
29pub mod metrics;
30pub mod middleware;
31/// Route definition and registration.
32pub mod routing;
33pub mod schedule;
34pub mod seeder;
35/// HTTP server builder and runner.
36pub mod server;
37pub mod session;
38pub(crate) mod static_files;
39pub mod tenant;
40pub mod testing;
41#[cfg(feature = "theme")]
42pub mod theme;
43pub mod validation;
44mod websocket;
45
46pub use api::api_key::{
47    generate_api_key, hash_api_key, verify_api_key_hash, ApiKeyInfo, ApiKeyMiddleware,
48    ApiKeyProvider, GeneratedApiKey,
49};
50pub use api::openapi::{
51    build_openapi_spec, openapi_docs_response, openapi_json_response, OpenApiConfig,
52};
53
54pub use app::Application;
55pub use auth::{
56    Auth, AuthMiddleware, AuthUser, Authenticatable, GuestMiddleware, OptionalUser, UserProvider,
57};
58pub use authorization::{AuthResponse, Authorizable, AuthorizationError, Authorize, Gate, Policy};
59pub use cache::{Cache, CacheConfig, CacheStore, InMemoryCache, RedisCache};
60pub use config::{
61    env, env_optional, env_required, AppConfig, Config, Environment, LangConfig, LangConfigBuilder,
62    ServerConfig,
63};
64pub use container::{App, Container};
65pub use csrf::{csrf_field, csrf_meta_tag, csrf_token, CsrfMiddleware};
66pub use database::{
67    AutoRouteBinding, Database, DatabaseConfig, DatabaseType, DbConnection, Model, ModelMut,
68    RouteBinding, DB,
69};
70// Re-export utoipa and utoipa-redoc for advanced OpenAPI customization
71pub use utoipa;
72pub use utoipa_redoc;
73
74// Re-export commonly used SeaORM traits for convenience
75// This saves users from having to add `use sea_orm::*` imports
76pub use error::{AppError, FrameworkError, HttpError, ValidationErrors};
77#[cfg(feature = "json-ui")]
78pub use ferro_json_ui::{
79    resolve_actions, resolve_actions_strict, resolve_errors, resolve_errors_all, Action,
80    ActionCardProps, ActionCardVariant, ActionOutcome, AlertProps, AlertVariant, AvatarProps,
81    BadgeProps, BadgeVariant, BreadcrumbItem, BreadcrumbProps, ButtonProps, ButtonType,
82    ButtonVariant, CardProps, CheckboxProps, ChecklistItem, ChecklistProps, Column, ColumnFormat,
83    Component, ComponentNode, ConfirmDialog, DashboardLayout, DashboardLayoutConfig,
84    DescriptionItem, DescriptionListProps, DialogVariant, FormProps, HeaderProps, HttpMethod,
85    IconPosition, ImageProps, InputProps, InputType, JsonUiConfig, JsonUiView, Layout,
86    LayoutContext, LayoutRegistry, ModalProps, NavItem, NotificationDropdownProps,
87    NotificationItem, NotifyVariant, Orientation, PaginationProps, ProgressProps, SelectOption,
88    SelectProps, SeparatorProps, SidebarGroup, SidebarNavItem, SidebarProps, SidebarSection, Size,
89    SkeletonProps, SortDirection, StatCardProps, SwitchProps, Tab, TableProps, TabsProps,
90    TextElement, TextProps, ToastProps, ToastVariant, Visibility as JsonUiVisibility,
91    VisibilityCondition, VisibilityOperator, SCHEMA_VERSION,
92};
93#[cfg(feature = "stripe")]
94pub use ferro_stripe::{
95    billing_portal_url, create_account_link, create_connect_checkout, create_subscription_checkout,
96    is_processed as stripe_is_processed, plan_from_subscription, plan_satisfies,
97    subscription_info_from_stripe, verify_webhook, ConnectAccount, Error as StripeError,
98    ProcessStripeWebhook, Stripe, StripeCheckoutCompleted, StripeConfig,
99    StripeConnectPaymentSucceeded, StripeInvoicePaid, StripeSubscriptionDeleted,
100    StripeSubscriptionUpdated, SubscriptionInfo, SubscriptionStatus,
101};
102#[cfg(feature = "theme")]
103pub use ferro_theme::{IntentModeTemplates, IntentSlotTemplate, Theme, ThemeError, ThemeTemplates};
104pub use hashing::{hash, needs_rehash, verify, DEFAULT_COST as HASH_DEFAULT_COST};
105pub use http::{
106    bytes, json, text, Cookie, CookieOptions, FormRequest, FromParam, FromRequest, HttpResponse,
107    InertiaRedirect, PaginationLinks, PaginationMeta, Redirect, Request, Resource,
108    ResourceCollection, ResourceMap, Response, ResponseExt, SameSite,
109};
110#[cfg(feature = "inertia")]
111pub use inertia::{Inertia, InertiaConfig, InertiaResponse, InertiaShared, SavedInertiaContext};
112#[cfg(feature = "json-ui")]
113pub use json_ui::JsonUi;
114pub use lang::{lang_choice, lang_init, locale, set_locale, t, trans, LangMiddleware};
115pub use sea_orm::{
116    ActiveModelTrait, ColumnTrait, EntityTrait, IntoActiveModel, ModelTrait, PaginatorTrait,
117    QueryFilter, QueryOrder, QuerySelect,
118};
119pub use session::{
120    invalidate_all_for_user, session, session_mut, DatabaseSessionDriver, SessionConfig,
121    SessionData, SessionMiddleware, SessionStore,
122};
123#[cfg(feature = "stripe")]
124pub use tenant::RequiresPlan;
125pub use tenant::{
126    current_tenant, DbTenantLookup, FrameworkTenantScopeProvider, HeaderResolver, JwtClaimResolver,
127    PathResolver, SubdomainResolver, TenantContext, TenantFailureMode, TenantLookup,
128    TenantMiddleware, TenantResolver, TenantScope,
129};
130#[cfg(feature = "theme")]
131pub use theme::{
132    current_theme, DefaultResolver, HeaderThemeResolver, TenantThemeResolver, ThemeMiddleware,
133    ThemeResolver,
134};
135// Deprecated - kept for backward compatibility
136#[cfg(feature = "inertia")]
137#[allow(deprecated)]
138pub use inertia::InertiaContext;
139pub use metrics::{get_metrics, MetricsSnapshot, RouteMetrics, RouteMetricsView};
140pub use middleware::{
141    register_global_middleware, Limit, LimiterResponse, MetricsMiddleware, Middleware,
142    MiddlewareFuture, MiddlewareRegistry, Next, RateLimiter, SecurityHeaders, Throttle,
143};
144pub use routing::{
145    // Internal functions used by macros (hidden from docs)
146    __box_handler,
147    __delete_impl,
148    __fallback_impl,
149    __get_impl,
150    __patch_impl,
151    __post_impl,
152    __put_impl,
153    get_registered_routes,
154    route,
155    validate_route_path,
156    FallbackDefBuilder,
157    GroupBuilder,
158    GroupDef,
159    GroupItem,
160    GroupRoute,
161    GroupRouter,
162    IntoGroupItem,
163    ResourceAction,
164    ResourceDef,
165    ResourceRoute,
166    RouteBuilder,
167    RouteDefBuilder,
168    RouteInfo,
169    Router,
170};
171pub use schedule::{CronExpression, DayOfWeek, Schedule, Task, TaskBuilder, TaskEntry, TaskResult};
172pub use seeder::{DatabaseSeeder, Seeder, SeederRegistry};
173pub use server::Server;
174
175// Re-export ferro-events for event-driven architecture
176pub use ferro_events::{
177    dispatch as dispatch_event, dispatch_sync, Error as EventError, Event, EventDispatcher,
178    Listener, ShouldQueue,
179};
180
181// Re-export ferro-queue for background job processing
182pub use ferro_queue::{
183    dispatch as queue_dispatch, dispatch_later, dispatch_to, register_tenant_capture_hook,
184    Error as QueueError, Job, JobPayload, PendingDispatch, Queue, QueueConfig, QueueConnection,
185    Queueable, TenantScopeProvider, Worker, WorkerConfig,
186};
187
188// Re-export ferro-notifications for multi-channel notifications
189pub use ferro_notifications::{
190    Channel as NotificationChannel, ChannelResult, DatabaseMessage, DatabaseNotificationStore,
191    Error as NotificationError, MailConfig, MailDriver, MailMessage, Notifiable, Notification,
192    NotificationConfig, NotificationDispatcher, ResendConfig, SlackAttachment, SlackField,
193    SlackMessage, SmtpConfig, StoredNotification,
194};
195
196// Re-export ferro-broadcast for real-time WebSocket channels
197pub use ferro_broadcast::{
198    AuthData, Broadcast, BroadcastBuilder, BroadcastConfig, BroadcastMessage, Broadcaster,
199    ChannelAuthorizer, ChannelInfo, ChannelType, Client as BroadcastClient, ClientMessage,
200    Error as BroadcastError, PresenceMember, ServerMessage,
201};
202
203// Re-export broadcasting auth handler
204pub use broadcast::broadcasting_auth;
205
206// Re-export ferro-storage for file storage abstraction
207pub use ferro_storage::{
208    Disk, DiskConfig, DiskDriver, Error as StorageError, FileMetadata, LocalDriver,
209    MemoryDriver as StorageMemoryDriver, PutOptions, Storage, StorageDriver, Visibility,
210};
211
212// Re-export ferro-cache for caching with tags
213pub use ferro_cache::{
214    Cache as TaggableCache, CacheConfig as TaggableCacheConfig, CacheStore as TaggableCacheStore,
215    Error as TaggableCacheError, MemoryStore as TaggableCacheMemoryStore, TaggedCache,
216};
217
218// Re-export ferro-lang for localization
219pub use ferro_lang::{LangError, Translator};
220
221// Re-export ferro-ai for AI classification and confirmation primitives
222#[cfg(feature = "ai")]
223pub use ferro_ai::{
224    AnthropicProvider, ClassificationProvider, ClassificationResult, Classifier, ClassifierConfig,
225    ConfirmationExpired, ConfirmationStore, Error as AiError, InMemoryConfirmationStore,
226    PendingActionInfo,
227};
228
229// Re-export ferro-whatsapp for WhatsApp Business Cloud API integration
230#[cfg(feature = "whatsapp")]
231pub use ferro_whatsapp::{
232    verify_whatsapp_webhook, DeduplicationStore, DeliveryStatus, Error as WhatsAppError,
233    InMemoryDeduplicationStore, Message as WhatsAppMessage, ProcessWhatsAppWebhook,
234    SendResult as WhatsAppSendResult, SenderIdentity, WhatsApp, WhatsAppConfig,
235    WhatsAppStatusUpdate, WhatsAppTextReceived,
236};
237
238// Re-export ferro-projections for service projection definitions
239#[cfg(feature = "projections")]
240pub use ferro_projections::{
241    derive_intents, infer_meaning, ActionDef, Cardinality, DataType, Error as ProjectionsError,
242    FieldDef, FieldMeaning, GuardDef, InputDef, Intent, IntentHint, IntentScore, JsonUiRenderer,
243    NavigationHint, RelationshipDef, RenderContext, RenderMode, Renderer, ServiceDef, StateDef,
244    StateMachine, Transition, Warning as ProjectionsWarning,
245};
246
247// Re-export async_trait for middleware implementations
248pub use async_trait::async_trait;
249
250// Re-export inventory for #[service(ConcreteType)] macro
251#[doc(hidden)]
252pub use inventory;
253
254// Re-export for macro usage
255#[doc(hidden)]
256pub use serde_json;
257
258// Re-export serde for InertiaProps derive macro
259pub use serde;
260
261// Re-export validator crate for derive-based validation
262pub use validator;
263pub use validator::Validate;
264
265// Re-export our Laravel-style validation module
266pub use validation::{
267    // Rules
268    accepted,
269    alpha,
270    alpha_dash,
271    alpha_num,
272    array,
273    between,
274    boolean,
275    confirmed,
276    date,
277    different,
278    email,
279    in_array,
280    integer,
281    max,
282    min,
283    not_in,
284    nullable,
285    numeric,
286    regex,
287    // Bridge
288    register_validation_translator,
289    required,
290    required_if,
291    same,
292    string,
293    url,
294    validate,
295    Rule,
296    TranslatorFn,
297    Validatable,
298    ValidationError,
299    Validator,
300};
301
302// Re-export the proc-macros for compile-time component validation and type safety
303pub use ferro_macros::domain_error;
304pub use ferro_macros::ferro_test;
305pub use ferro_macros::handler;
306pub use ferro_macros::inertia_response;
307pub use ferro_macros::injectable;
308pub use ferro_macros::redirect;
309pub use ferro_macros::request;
310pub use ferro_macros::service;
311pub use ferro_macros::ApiResource;
312pub use ferro_macros::FerroModel;
313pub use ferro_macros::FormRequest as FormRequestDerive;
314pub use ferro_macros::InertiaProps;
315pub use ferro_macros::ValidateRules;
316
317// Re-export Jest-like testing macros
318pub use ferro_macros::describe;
319pub use ferro_macros::test;
320
321// Re-export testing utilities
322pub use testing::{
323    Factory, FactoryBuilder, Fake, Sequence, TestClient, TestContainer, TestContainerGuard,
324    TestDatabase, TestRequestBuilder, TestResponse,
325};
326
327/// Return a JSON response from a handler using `serde_json::json!` syntax.
328///
329/// # Example
330///
331/// ```rust,ignore
332/// use ferro_rs::json_response;
333///
334/// pub async fn index() -> Response {
335///     json_response!({ "status": "ok" })
336/// }
337/// ```
338#[macro_export]
339macro_rules! json_response {
340    ($($json:tt)+) => {
341        Ok($crate::HttpResponse::json($crate::serde_json::json!($($json)+)))
342    };
343}
344
345/// Return a plain-text response from a handler.
346///
347/// # Example
348///
349/// ```rust,ignore
350/// use ferro_rs::text_response;
351///
352/// pub async fn ping() -> Response {
353///     text_response!("pong")
354/// }
355/// ```
356#[macro_export]
357macro_rules! text_response {
358    ($text:expr) => {
359        Ok($crate::HttpResponse::text($text))
360    };
361}
362
363/// Register global middleware that runs on every request
364///
365/// Global middleware is registered in `bootstrap.rs` and runs in registration order,
366/// before any route-specific middleware.
367///
368/// # Example
369///
370/// ```rust,ignore
371/// // In bootstrap.rs
372/// use ferro_rs::global_middleware;
373/// use ferro_rs::middleware;
374///
375/// pub fn register() {
376///     global_middleware!(middleware::LoggingMiddleware);
377///     global_middleware!(middleware::CorsMiddleware);
378/// }
379/// ```
380#[macro_export]
381macro_rules! global_middleware {
382    ($middleware:expr) => {
383        $crate::register_global_middleware($middleware)
384    };
385}
386
387/// Create an expectation for fluent assertions
388///
389/// # Example
390///
391/// ```rust,ignore
392/// use ferro_rs::expect;
393///
394/// expect!(actual).to_equal(expected);
395/// expect!(result).to_be_ok();
396/// expect!(vec).to_have_length(3);
397/// ```
398///
399/// On failure, shows clear output:
400/// ```text
401/// Test: "returns all todos"
402///   at src/actions/todo_action.rs:25
403///
404///   expect!(actual).to_equal(expected)
405///
406///   Expected: 0
407///   Received: 3
408/// ```
409#[macro_export]
410macro_rules! expect {
411    ($value:expr) => {
412        $crate::testing::Expect::new($value, concat!(file!(), ":", line!()))
413    };
414}
ferro_rs/lib.rs

ferro_rs/
lib.rs
