# Giterated Stack

Giterated stack is the unified protocol stack implementation for Giterated. The architecture of the Giterated Stack allows for easy re-use of the same stack handling code across the entire Giterated ecosystem, from daemon to client.

# Architecture

Giterated's protocol operates using `Operation`'s on `Object`'s. The structure of a message is as follows:
```
object: String,
operation_name: String,
operation_payload: Vec<u8>
```

This same structure is represented in the Giterated Stack. Operations are implemented in terms of handlers, with a specific Object type and Operation type pair. For example:

```
async fn foo_handler(object: &User, operation: &FooOperation, state: FooState) -> Result<FooResult, OperationError<FooError>> {
    todo!()
}
```

These handlers are then inserted into a handler structure that, at runtime, inspects the type signatures of the handlers and determines there are no issues. All operations flow through the handler structure and are transparently passed to handler functions.

## Operations and their Types

Operations have their response and error types encoded in the type system using the `GiteratedOperation<O>` trait. Here is an example of how the operation used above would be defined.

```
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct FooOperation {
    pub bar: u64
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct FooResult {
    pub baz: u64
}

#[derive(Debug, Serialize, Deserialize, thiserror::Error)]
#[error("foo error")]
pub struct FooError;

// GiteratedOperation additionally specifies which object type the operation
// uses. In this example, we're implementing it for the User object.
impl GiteratedOperation<User> for FooOperation {
    type Success = FooResult;
    type Failure = FooError;
}
```

These trait implementations further guard operation handlers from being incorrect, as a function with mismatched parameters or return type is not a valid operation handler.

## Routing Operations to Handlers

All incoming operations are processed through the `TODO` type. This type will, at runtime, generate a LUT that matches object types to their operation handlers.

At this time, it is not valid for multiple handlers to handle the same operation on the same object type. The `TODO` type also verifies this is not the case at startup to prevent conflicts at runtime.

## Defining a new Operation

A new operation can be implemented on any valid `GiteratedObject` type. This means it is easy to extend the behaviour of existing Object types to add new behaviours in-tree, and custom behaviours with plugins.