Skip to content

design.md

Latest commit

 

History

History
184 lines (130 loc) · 6.09 KB

design.md

File metadata and controls

184 lines (130 loc) · 6.09 KB
Raw

Ellis - Design Guide

This document explains the high-level design of Ellis, the Clearwater provisioning server. It gives an overview of the major components and interfaces, and provides pointers into the code. It is intended for people who wish to modify, fix, or extend Ellis.

Requirement

Ellis provides the ability to configure lines in Homestead and Homer through a convenient interface. It is intended to showcase the abilities of Clearwater, but it is not itself part of the Clearwater core. In particular:

  • Ellis is not designed for high performance.
  • Ellis does not support scaling beyond a single instance.
  • Ellis GUI is only tested on Firefox and Chrome browsers, and on desktop only (not mobile).

Overview

The core of Ellis is a web server which provides an HTTP API for provisioning operations. This accesses:

  • An internal database of users and passwords, via SQL. A user may have multiple lines (i.e., phone numbers). The user concept applies only to Ellis; it has no representation elsewhere in Clearwater.

  • An internal database of telephone numbers, from which new lines are provisioned, via SQL.

  • Per-line subscriber configuration stored in Homestead (which may itself be acting as a caching layer in front of an HSS), via the documented Homestead HTTP API.

  • Per-line call-service configuration for Clearwater's internal MMTEL application server, stored in Homer (which acts as an XDMS), via Ut (i.e., ETSI simservs XML over HTTP).

  • (Optionally:) An email smarthost, for sending forgotten-password emails, via SMTP.

The Ellis GUI is a web application built on top of the HTTP API. It is served statically by the Ellis core for convenience, but everything it does is achieved via the API. The API is also available for other clients to use.

Ellis also contains a collection of scripts for building, packaging, installation, configuration, and backup.

The subsequent sections consider each component of Ellis in detail.

Ellis core

The Ellis core is written in Python, using the Tornado web server component. The main entry point is src/metaswitch/ellis/main.py.

metaswitch.ellis.api

This module defines the exposed HTTP API. All the actual work is handed off to other modules.

  • The served URLs are listed in __init__.py.

  • The base HTTP handler for Ellis is defined in _base.py. This includes API key handling, login, success and error returns, and so on.

The URLs are handled by different modules according to topic.

Sessions are handled by session.py, using metaswitch.ellis.data.users to verify the credentials and _base to perform the login itself.

Users are handled by users.py, using metaswitch.ellis.data to access the local database and metaswitch.ellis.remote to access Homestead and Homer. This includes forgotten-password handling, which also uses metaswitch.ellis.mail.

Numbers (i.e., lines) are handled by numbers.py, using metaswitch.ellis.data to access the local databases and metaswitch.ellis.remote to access Homestead and Homer. This includes Global Address Book (GAB) handling.

metaswitch.ellis.data

This module provides a binding for the two MySQL tables used by Ellis. This uses SQLAlchemy for database access, although we use very few of SQLAlchemy's features.

The database schema and upgrade script are also kept here.

metaswitch.ellis.mail

This module uses Python's built-in smtplib to send a password recovery email. The email is generated by a Tornado template.

metaswitch.ellis.remote

This module provides bindings for the two remote databases: Homestead (HSS) and Homer (Simservs). These are both accessed over RESTful HTTP APIs, for which we use Tornado's asynchronous httpclient.

metaswitch.common

(This comes from the python-common submodule, and appears at common/metaswitch/common/.)

This module contains assorted utilities shared between different components of the Clearwater system.

It also contains the default simservs document used for new users.

Ellis GUI

The Ellis GUI is written in Javascript. It is served statically by metaswitch.ellis.api (see __init__.py), and performs all its updates via the HTTP API presented by the Ellis core. The code is in web-content/.

Framework

The Ellis GUI uses jQuery throughout, and layout is handled by Bootstrap. Newer pages (e.g., the address book) use the Backbone framework, but some have not yet been migrated (e.g., the dashboard) and just use plain jQuery and helpers in common.js for wiring.

Structure

The application is structured as a small number of pages, each of which has an HTML file and a corresponding Javascript file. Data and functions belonging to the application as a whole are placed in the clearwater and app objects to avoid polluting the global namespace.

All the elements of the main (dashboard) page are contained in index.html - the row templates, modal dialogs, panes, and alerts are all inline, controlled via code in app.js. This includes call services configuration, which is handled by panes within a modal dialog.

The address book uses the Backbone framework, which makes the code a lot cleaner. The template used for the rows is loaded from web-content/js/templates/, rather than being placed inline.

The signup and reset-password pages use zxcvbn to help users pick a strong password. This client code is stricter than the password requirements enforced by the server, but this is not a significant exposure.

The login and forgot-password and pages are straightforward jQuery-driven pages.

Other

Demo account expiry

Users can be configured as "demo accounts", in which case they expire automatically (along with all their numbers) after one week. This is handled by a cron job, debian/ellis.cron.daily, which is installed automatically by the Debian package handling code.