# 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

```cpp
struct packet;

main()
{
	pio = packet_io_create(mode);
	dev = packet_io_open_device(pio, dev_name);
	while(1)
		work_base_loop(dev);
}

worker_base_loop(dev)
{
  struct packet *rx_pkt;

  rx_pkt_num = packet_io_rx(dev, &rx_pkt, 1);

  if(rx_pkt_num > 0)
  {
  	//ingress processing: Tunnel decoding, IP defragmentation, Protocol decoding, trigger build in session events
  	event = session_manager(rx_pkt);

  	//event dispatch
  	plugin_manager(event);

  	//egress processing: AMQ
  	rl_group_id[] =pkt_get_group_id(rx_pkt);

        if(rl_group_id[])
  		AMQ_enqueue(rl_group_id[], rx_pkt);

  	packet_io_tx(&rx_pkt, 1);
  }
}
```

## Plugin Manager

Plugin Management APIs

```cpp
/*
 * The pm_session_dettach_me just sets the flag to disable this plugin and no longer call this event callback.
 * Before calling pm_session_dettach_me, the current plugin must release related resources for the current session.
 */
pm_session_dettach_me(session);

/*
 * The current plugin(cb2) takes over the current session, the pm_session_take_over setting flag disables other plugins,
 * and the current session does not call other plugins except for the SESSION_EVENT_CLOSING event.
 *
 *                               +-----+   +-----+   +-----+   +-----+
 * Plugin runtime callback list: | cb1 |-->| cb2 |-->| cb3 |-->| cb4 |
 *                               +-----+   +-----+   +-----+   +-----+
 *                                           /|\
 *                                            |
 *                         plugin cb2 run pm_session_take_over
 * 
 * A plugin(cb1/cb3/cb4) that is taken over, if the plugin was called before being taken over and has a registered SESSION_EVENT_CLOSING event,
 * it will be called again when the SESSION_EVENT_CLOSING event comes. Otherwise, the plugin will not be called.
 */
pm_session_take_over(session);
```

## Session Manager

Session Management APIs

```cpp
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

```cpp
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_take_over(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);
  }
}
```