# Stellar: A stateful network functions development platform

A stateful network function could be a firewall, a load balancer, or an IDS. 

## Architecture

The stellar components are:

- **Packet IO** built an abstraction of network IO devices.
- **Session Manager** has a hash table for tracking sessions. The caller feeds packets to the session manager and may return triggered session events.
- **Plugin Manager** loads C/Lua plugins and manages per-plugin, per-session context. When the caller feeds an event to the plugin manager, it invokes plugin callbacks.
- **Protocol Decoders** are libraries that parse and extract information from the packet payload.
- **Active Queue Management** is queue management algorithm libraries that schedule packets by buffering, forwarding, marking, or dropping. A plugin creates a queue instance and enqueues packets as its needs. 
  - Question: Who consumes the dequeue events?

![stellar-high-level-design](./docs/imgs/stellar-high-level-design.svg)

## Packet IO Library
```
struct packet
{
  enum io_type type;
  void *raw_pkt;  
}
packet_io_loop()
{
  packet_io_rx(&rx_pkt)
  //ingress processing: Tunnel decoding, IP defragmentation
  session_manager();
  plugin_manager();
  //egress processing: AMQ
  rl_group_id=pkt_get_group_id(rx_pkt);
  void *raw_pkt=pkt_get_raw(rx_pkt);
  AMQ_enqueue(group_id[], raw_pkt, pkt_sz);

}
```

## Plugin Manager

Plugin Management APIs

```
/*
 * The plugin manager just set the skip flag and don't call this event callback next.
 * Before calling pm_session_dettach_me, the current plugin must release related resources for the current session.
 */
pm_session_dettach_me(session);

/*
 * The plugin manager uses ERROR_EVENT_DETTACH to call other plugin error callbacks, 
 * and when the plugin error callback handler is called, 
 * the error callback handler must release the relevant resources for the current session.
 */
pm_session_dettach_others(session);
```

## Session Manager

Session Management APIs

```
session_drop_current_packet(session);
session_set_ratelimit_group(session, rl_group_id);
session_set_metadata(session, const char *key, void *value, size_t val_sz, free_callback);
session_get_metadata(session, const char *key, void **value, size_t *val_sz);
session_del_metadata(session, key)
session_lock(session, plug_id);
session_unlock(session, plug_id);

```
Plugin Example
```
plugin_entry(session, pme)
{
  session_get_metadata(session, "fw_action", value);
  if(value==INTERCEPT)
  {
    //pm_session_dettach_me(session);
    return;
  }
  ret=check_security_policy(session);
  if(ret==INTERCEPT)
  {
    pm_session_dettach_others(session);
  }
  else if(ret==RATE_LIMIT)
  {
    group_id=security_policy_id;
    amq_group_create(group_id, CIR, CBS);
    session_set_ratelimit_group(session, group_id);
  }
}
```