Crate intrepid_core

Expand description

§Intrepid Core

Intrepid is a magic handler kit where most of the boilerplate work is already done. For cases where you’d like to get the ergonomics of Bevy or Actix-Web, but for your own stuff.

Intrepid core holds its interior concepts in the Core crate. Those are:

Frames (Frame); a type that represents a few different byte-forward structures.
Handlers (Handler); a trait that applies to handlers which can asynchronously work with frames.
Actions (Action); functions that we can treat as handlers.
Systems (System); bundles of actions grouped together that can be dispatched one frame over a bunch of actions.

All of this is a bunch of boilerplate managed to enable the intrepid core concept, which is this: you should be able to write your app logic once and then compose and recompose it a bunch of different ways.

Intrepid wants you to split your program into three groups:

Data; the things that you can turn into bytes and back. This is a hard limit on your program: it’s something that you can persist or transmit outside of your program if you need.
State; the part of your program that gets shared across it at runtime. Sometimes state is serializable, sometimes it’s not! For example, your database connection is state.
Behavior; the actual functions of your program themselves. These are async functions that need to know about your data and state, and only your data and state.

If you’re able to split your code up like this, intrepid rewards you with a ton of bonus ergonomics by letting you write most of your code in the form of types and async functions that use those types. It lets you make business logic out of a function and then turn that function into a reusable thing that you can pop into place all over your codebase, or use directly in pretty fancy ways.

Structs§

Action: The Action struct wraps an action state that describes the progression of a handler from a function-like thing into a full-blown frame service.
Active: The Active type state represents an action which is ready to be invoked as a service.
Context: The context of the action. This is handed into actions when they’re invoked, and is the underpinning mechanism for distributing side-effects, as well as action composition.
Endpoint: An action that can be invoked as a service.
FrameFuture: A future that resolves to a Result<Frame>
FrameOutbox: An outbox for sending frames to an actionable stream.
HttpFrameMeta: Metadata for a HTTP frame built from an axum request.
HttpFrameResponse: An intrepid frame being turned into an axum json response.
HttpFrameResponseError: An intrepid error being turned into an axum response.
HttpGet: Extract the URI of a message from a frame.
HttpMeta: Extract the URI of a message from a frame.
HttpPost: Extract the URI of a message from a frame.
HttpRequestFrame: An HTTP frame built from an axum request.
JsonHttpFrameResponse: An intrepid frame being turned into an axum response.
Message: Retrieve a MessageFrame from a Frame, but only if the frame is a message.
MessageData: Extract the raw data of a message from a frame. This gives you the unprocessed data of the message in Bytes form. Other parts of the system presume JSON encoding and things like that, but this will let you determine what format you like.
MessageFrame: An addressed frame.
MessageJson: Extracts a JSON-serializable type from a message frame.
MessageMeta: Extract the raw metadata of a message from a frame. This gives you the unprocessed metadata of the message in Bytes form. Other parts of the system presume JSON encoding and things like that, but this will let you determine what format you like.
MessageMetaJson: Extracts a JSON-serializable type from a message frame’s meta.
MessageUri: Extract the URI of a message from a frame.
MetaMismatchError: If the frame doesn’t have the right meta content.
Path: A path extractor that captures a given type from a frame. This is used to extract path captures from a message frame’s URI, turning them into local types. It obeys a few rules:
Pattern: A wrapper for a URL pattern, which can be used to match URLs and extract data from them.
PlainHttpFrameResponse: An intrepid frame being turned into an axum json response.
Ready: A Ready type state represents an action which has a handler and a state, and can be invoked
RouteId: A route ID is a unique identifier for a route. This is a wrapper around a UUID.
Router: A router for actions that can be invoked as services.
Routes: A collection of routes that can be mounted on a router. This isn’t where the endpoints are stored, but is instead an index to track those endpoints.
State: Retrieve the state an action expects. This has the side-effect of creating a state dependency for the action. All actions in a given system must share the same state type.
StateNotReadyError: An error indicating that the state is not ready.
Stateless: A Ready type state represents an action which has a handler and a state, and can be invoked
SystemContext: A router for actions that can be invoked as services.
WrongFrameError: Sometimes the frame isn’t a message when we expect it to be.

Enums§

ActionContext: An action context, describing any additional context that the action may carry. This is used to distribute system setup information when invoking them as actions, for example, when systems have defined action routes.
Error: A collection of errors that can occur in this crate.
ExtractorError: An error that occurs when extracting data from a frame.
Frame: A frame that can be processed by an action.
MessageFrameError: Errors with managing message parts.
PathError: These errors can occur when trying to deserialize frame messages.
PatternError: An error that occurs when creating a pattern.
System: A system is a collection of actions that can be invoked as services.

Traits§

Actionable: Allows actions to be type erased into dynamic boxed containers.
Extractor: Implement extract to allow for extracting values from an action.
Handler: An action is an async function that can be turned into an frame handler.

Type Aliases§

ActionService: A convenience type alias for a service that takes an Frame and returns a Vec<Frame>.
Actions: A collection of actions that can be invoked.
ActiveAction: A convenience type alias for an active action.
BoxedAction: A single boxed action that can be invoked.
CandidateAction: A convenience type for an action candidate
ReadyAction: A convenience type for an action ready status.
Result: The result type for this crate.
StatefulSystem: A system which knows a state that lines up with the actions it contains. It’s possible to create a stateful system from an open system, and it’s possible to transition to it from a stateless system, if that system is given a handler that requires state. However, it’s not possible to transition from a stateful system to a stateless system.
StatelessSystem: A system which has been finalized without state. We can handle frames with this system.