src/connectivity/network/netstack3/docs/CORE_BINDINGS.md

# Core and Bindings

This document describes and motivates the design of the netstack into separate
"core" and "bindings" components.

## Architecture

The netstack codebase is split into two crates - the `core` crate, and the
top-level `netstack3` crate. We refer to these as the "core" and bindings"
respectively.

The core is a library crate, and contains most of the logic of the netstack.
However, it is also platform-agnostic. Any client of the core which produces a
binary is known as "bindings" because they bind the core to a particular
platform. Currently, `netstack3` crate, which provides bindings to Fuchsia, is
the only bindings crate in existence.

## Benefits

This section explores some of the major benefits of the core/bindings split.

### "Functional core/imperative shell"

The core/bindings split naturally implements a [functional core/imperative
shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell)
design pattern. In this pattern, the bulk of the application logic lives in a
"functional core" which concerns itself with the high-level tasks of the
application. Ideally, the functional core can be unaware of "real world" details
like execution order, communication with the outside world, input validation,
etc. The "imperative shell", on the other hand, concerns itself with all of the
real world details that the functional core ignores.

*NOTE: In the original "functional core/imperative shell" concept, the
functional core is functional in the sense of not having any mutable state. Our
core is not functional in this sense, but our architecture still shares many
properties with that design, so the comparison still makes sense.*

This architecture provides us with a number of benefits:
- High-level testing of the core is easy. Since, to the core, the outside world
  simply looks like a trait implementation, mocking out the entire world is
  simply a matter of implementing that trait (in particular, the
  `EventDispatcher` trait). The core's `testutil::DummyEventDispatcher` serves
  this purpose, and allows many of our tests to create an entire mocked
  execution environment, execute a sequence of actions, and test to see that the
  right events were emitted in response, and in only a few lines of code.
- The core can be largely infallible. It can provide types and methods whose
  signatures force the bindings to perform any input validation ahead of time
  before calling into the core. This both simplifies the core, and also forces
  the best practice of validating external input as early as possible.
- While the core must, at a minimum, enable whatever execution model the
  bindings want to use (e.g., if the core's data structures are not thread-safe,
  then the bindings cannot execute across multiple threads), it can simply
  expose functions and leave it up to the bindings to call those functions at
  appropriate times.

### Ease of development

Since the core is platform-agnostic, it doesn't require Fuchsia's full build
system to develop on. In fact, the author of this document usually develops by
using the normal `cargo` tool rather than the Fuchsia-specific `fx` or `fargo`
tools. This unlocks both fast development cycles and the full suite of `cargo`
tooling.

### Platform-agnosticism

With the core being platform-agnostic, it should be possible to port the
netstack to other platforms with relative ease.