Trait do_proxy::DoProxy

pub trait DoProxywhere
    Self: Sized,{
    type Init: Serialize + DeserializeOwned + 'static;
    type Request: Serialize + DeserializeOwned + 'static;
    type Response: Serialize + DeserializeOwned + 'static;
    type Error: Serialize + DeserializeOwned + Error;

    const BINDING: &'static str;

    fn load_from_storage<'life0, 'async_trait>(
        ctx: &'life0 mut Ctx<'_>
    ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait;
    fn handle<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        ctx: &'life1 mut Ctx<'_>,
        req: ProxiedRequest<Self::Request>
    ) -> Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + 'async_trait>>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait;

    fn init<'life0, 'async_trait>(
        ctx: &'life0 mut Ctx<'_>,
        init: Self::Init
    ) -> Pin<Box<dyn Future<Output = Result<(), Self::Error>> + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait,
    { ... }
    fn run_request<'life0, 'life1, 'async_trait>(
        cached_proxy: &'life0 mut Option<Self>,
        ctx: &'life1 mut Ctx<'_>,
        req: Option<Request>
    ) -> Pin<Box<dyn Future<Output = Result<Response>> + 'async_trait>>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        Self: 'async_trait,
    { ... }
}

The DoProxy trait is the main interface of this library. Implement this trait for a type you want to make into a durable object and automatically get many helper methods for interacting with it.

After implementing this trait, use the macro do_proxy! to generate the workers-rs worker::DurableObject glue code.

See the crates under examples/* for example implementations.

Required Associated Types

type Init: Serialize + DeserializeOwned + 'static

The initialization data that will be passed to the the object when it is first created. This should be used to set data that is expected to always be available when the object loads. For example, the first time a Person object is created, it should be initialized with the person’s name. This way when load_from_storage is called, we can expect a stored name field to always be present. If it is not present, then the object has not yet been initialized and load_from_storage should error.

Example

struct NewPerson {
    name: String,
    birthday: DateTime<Utc>,
}

type Request: Serialize + DeserializeOwned + 'static

The request type that will be sent to the object. This is generally an enum of all of the different “commands” that the object can handle.

Example

enum PersonRequest {
    GetAge,
    GetNextBirthday,
    GetName,
}

type Response: Serialize + DeserializeOwned + 'static

The response type that will be sent back from the object This is generally an enum of all of the different “responses” that the object can send.

Note, types like Option<serde_json::Value> will work!

Example

enum PersonResponse {
    Age(usize),
    Birthday(chrono::DateTime<chrono::Utc>),
    GetName(String),
}

type Error: Serialize + DeserializeOwned + Error

The error type that will be returned from the object. This lets users cleanly (kind of) pass errors from the object back to the caller.

Example

enum PersonError {
    NotYetBorn,
}

Required Associated Constants

const BINDING: &'static str

The Durable Object’s binding. Must be the same as the one written in your wrangler.toml. For example, INSERTER_OBJECT.

Required Methods

fn load_from_storage<'life0, 'async_trait>(
    ctx: &'life0 mut Ctx<'_>
) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Called when the object is first loaded into memory. This function is generally called only once when the Durable Object first receives a request. If the object is evicted from memory and then later receives a request, this function will be called again.

fn handle<'life0, 'life1, 'async_trait>(
    &'life0 mut self,
    ctx: &'life1 mut Ctx<'_>,
    req: ProxiedRequest<Self::Request>
) -> Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + 'async_trait>>where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait,

Called when the object receives a fetch request or an alarm. This is generally where you would match on Self::Request and call the appropriate function.

Provided Methods

fn init<'life0, 'async_trait>(
    ctx: &'life0 mut Ctx<'_>,
    init: Self::Init
) -> Pin<Box<dyn Future<Output = Result<(), Self::Error>> + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Called if the object is sent an init request. This function may be called multiple times and implemeting it is optional.

fn run_request<'life0, 'life1, 'async_trait>(
    cached_proxy: &'life0 mut Option<Self>,
    ctx: &'life1 mut Ctx<'_>,
    req: Option<Request>
) -> Pin<Box<dyn Future<Output = Result<Response>> + 'async_trait>>where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait,

This function wraps the handle function and handles the boilerplate of caching, converting between the different transport types, and error handling.

You should never implement this function, however you can if you need to.

Implementors