North Bound Code Refactor¶

Model Definition¶

We will use jsonmodels [1] to define models. The model definition will look like this:

@register_model
@construct_nb_db_model(
    indexes=Namespace(id='id'),
    events=('create', 'update', 'delete'),
)
class <Model>(<ModelBaseClass>, <ModelMixins>):
    # Fields
    <ModelField1> = jsonmodels.StringField()
    <ModelReferenceField1> = jsonmodels.RefField()

    <CRUD hooks>

    # Additional methods, if necessary, e.g. lports external fields

<ModelBaseClass> will be a base class all models inherit.

Models will be registered via the register_model method. This method can be used as a decorator, or called directly with the model.

External modules or model classes will have to register themselves manually in a configuration file.

<ModelMixins> can be used to add additional recurring features to the model. For instance, a unique key.

<CRUD hooks> are optional method definitions that will be called upon CRUD operations performed in NbApi, e.g.

• on_create_pre - Called on the object before its being inserted for the first time into the database, for example allocating a unique key.
• on_update_pre - Called on the object each time it is updated, can be used for example to generate a new version or trigger updates on other objects.

Since those hooks are methods on objects themselves, we can use super() to chain all needed hooks in parents and mixins, according to Python’s native MRO.

The construct_nb_db_model decorator constructs the model as a NB DB model. The metadata passed to it provides additional necessary information such as search indexes and events. If some metadata is not provided, the relevant information is taken from the parent classes and mixins.

The model class itself will hold the list of fields available on the object. The instance will have attributes holding the fields’ data.

These attributes can be made properties (rather than just holding the data) with information added to the Field object. This feature will only be added if we see it is necessary.

References are special kinds of fields. They have the type RefField or NestedField, depending whether the field is referenced by its ID, or held inline within the object, respectively.

For example, a logical port references a network by its ID, so the definition will be:

network = models.RefField(model='Network')

In another example, networks reference their subnets and contain the subnet object. Therefore, the subnet definition within the network will be:

subnet = models.NestedField(model='Subnet')

In this example, we assume exactly one subnet per network.

In both cases, when referencing the field, it will look as though the field is nested within the parent model. If only the id field is accessed in a RefField reference, then the ID will be returned. If a different field is accessed, the model object will be retrieved.

This behaviour can be controlled, and the complete model object can be retrieved a-priori.

The contained object may be a cached object, and that cache may be invalidated. In such a case, the cache will mark the object as cache-invalid, and the object will be re-read the next time it is accessed. This marking is possible, since the object’s reference is stored.

If nested resources are plural, e.g. a list, then the field will be defined as a ListField. e.g. for subnets in networks:

::

subnets = models.ListField(models.NestedField(…))

The metadata parameter indexes will provided the indexes that should be constructed around the model. This is to facilitate lookup by field value or filtering. An indexed field will allow looking up models that have a specific value in that field.

As noted below, indexing nested object will also be supported. The reference is done using dotted-notation, e.g. router.ports.mac.

Additionally, indexing by more than one field will also be supported, using a tuple of fields. e.g. indexing an lport by both chassis name and network id will look like this: chassis_net=(‘chassis.name’, ‘network.id’).

To support dynamic definition of events, i.e. to allow each model to define its events, there will be an events metadata parameter. It will be defined in greater detail upon southbound refactor.

The class can be extended with additional or overriding methods, if necessary.

Searching and Indexing¶

As part of the requirements, a model developer should have a way to inform the DB Store (in-memory cache) of which indexing and retrieval methods the model needs to support. e.g.

• get all resources filtered by a field:
  • ports by chassis
  • ports by name
  • floating IP by gateway
• get all resources filtered by a nested field:
  • router by router interface mac, i.e. router by router interface, router interface by mac.
• get first item, possibly filtered by topic or other fields:
  • get first floating ip in a network

For these requirements, it is enough to define on a model the fields by which it will be filtered. The internal DB store implementation will index the cached instances by these fields (even if they are nested), and upon request use these fields to extract the relevant instance.