openrvdas.server.server_api

  1#!/usr/bin/env python3
  2"""
  3API for interacting with data store. Implementations should subclass.
  4"""
  5import logging
  6import sys
  7
  8
  9################################################################################
 10class ServerAPI:
 11    """Abstract base class defining an API through which a LoggerServer
 12    can interact with a data store.
 13
 14    Parameters below have the following semantics:
 15    ```
 16    configuration - dict definition of a OpenRVDAS configuration
 17    mode          - dict name of mode, and logger_config_names associated with that mode
 18    default_mode  - name of mode to use at startup or when returning to a default state
 19
 20    logger_config_name - string name of a logger configuration, unique within configration
 21    logger_config - dict definition of a logger configuration
 22
 23    logger_id     - string name of logger, unique within cruise
 24    logger        - dict definition of logger, including list of names of
 25                    valid configs and optional host restriction
 26
 27    logger_configs - dict of {logger_config_name:logger_config,...}
 28    ```
 29    For the purposes of documentation below, assume a sample
 30    cruise_config as follows:
 31    ```
 32    {
 33      "loggers": {
 34        "knud": {
 35          "host": "knud.pi",
 36          "configs": ["off", "knud->net", "knud->file/net/db"]
 37        },
 38        "gyr1": {
 39          "configs": ["off", "gyr1->net", "gyr1->file/net/db"]
 40        },
 41      "modes": {
 42        "off": {"knud": "off", "gyr1": "off"},
 43        "port": {"knud": "off", "gyr1": "gyr1->net"},
 44        "underway": { "knud": "knud->file/net/db",
 45                      "gyr1": "gyr1->file/net/db"
 46                    }
 47      },
 48      "default_mode": "off",
 49      "configs": {
 50        "off": {},
 51        "knud->net": { config_spec },
 52        "knud->file/net/db": { config_spec },
 53        "gyr1->net": { config_spec },
 54        "gyr1->file/net/dbnet": { config_spec }
 55      }
 56    }
 57    ```
 58    """
 59
 60    ############################
 61    def __init__(self):
 62        # Called when we update which configs are active.
 63        self.update_callbacks = []
 64
 65        # Called when the set of configs changes.
 66        self.load_callbacks = []
 67
 68        # Called, obviously, when 'quit' is signalled.
 69        self.quit_callbacks = []
 70
 71    #############################
 72    # API methods below are used in querying/modifying the API for the
 73    # record of the running state of loggers.
 74    #############################
 75    # def get_cruises(self):
 76    #   """Return list of cruise id's. Returns, e.g.
 77    #   > api.get_cruises()
 78    #       ["NBP1700", "NBP1701"]
 79    #   """
 80    #   raise NotImplementedError('get_cruises must be implemented by subclass')
 81
 82    #############################
 83    def get_configuration(self):
 84        """Get OpenRVDAS configuration from the data store.
 85        """
 86        raise NotImplementedError('get_configuration must be implemented by subclass')
 87
 88    #############################
 89    def get_modes(self):
 90        """Get the list of modes from the data store.
 91        > api.get_modes()
 92            ["off", "port", "underway"]
 93        """
 94        raise NotImplementedError('get_modes must be implemented by subclass')
 95
 96    #############################
 97    def get_active_mode(self):
 98        """Get the currently active mode from the data store.
 99        > api.get_active_mode()
100            "port"
101        """
102        raise NotImplementedError('get_active_mode must be implemented by subclass')
103
104    #############################
105    def get_default_mode(self):
106        """Get the default mode from the data store.
107        > api.get_default_mode()
108            "off"
109        """
110        raise NotImplementedError('get_default_mode must be implemented by subclass')
111
112    #############################
113    def get_loggers(self):
114        """Get the dict of {logger_id:logger_spec,...} from the data store.
115        > api.get_loggers()
116            {
117              "knud": {"host": "knud.pi", "configs":...},
118              "gyr1": {"configs":...}
119            }
120        """
121        raise NotImplementedError('get_loggers must be implemented by subclass')
122
123    #############################
124    def get_logger(self, logger_id):
125        """Retrieve the logger spec for the specified logger id.
126        > api.get_logger('knud')
127            {"name": "knud->net", "host_id": "knud.pi", "configs":...}
128        """
129        raise NotImplementedError('get_logger must be implemented by subclass')
130
131    #############################
132    def get_logger_config(self, config_name):
133        """Retrieve the logger config associated with the specified name.
134        > api.get_logger_config('knud->net')
135               { "readers": [...], "transforms": [...], "writers": [...] }
136        """
137        raise NotImplementedError('get_logger_config must be implemented by subclass')
138
139    #############################
140    def get_logger_configs(self, mode=None):
141        """Retrieve the configs associated with a mode from the data store.
142        If mode is omitted, retrieve configs associated with the active mode.
143        > api.get_logger_configs()
144               {"knud": { config_spec },
145                "gyr1": { config_spec }
146               }
147        """
148        raise NotImplementedError('get_logger_configs must be implemented by subclass')
149
150    #############################
151    def get_logger_config_name(self, logger_id, mode=None):
152        """Retrieve the name of the logger config associated with the
153        specified logger in the specified mode. If mode is omitted,
154        retrieve config name associated with the active mode.
155        > api.get_logger_config_name('knud')
156            knud->net
157       """
158        raise NotImplementedError(
159            'get_logger_config_name must be implemented by subclass')
160
161    #############################
162    def get_logger_config_names(self, logger_id):
163        """Retrieve list of logger config names for the specified logger.
164        > api.get_logger_config_names('knud')
165            ["off", "knud->net", "knud->net/file", "knud->net/file/db"]
166        """
167        raise NotImplementedError(
168            'get_logger_config_names must be implemented by subclass')
169
170    ############################
171    # Methods for manipulating the desired state via API to indicate
172    # current mode and which loggers should be in which configs.
173    #
174    # These are triggered from the user/API/web interface
175    ############################
176    def set_active_mode(self, mode):
177        """Set the active mode for OpenRVDAS.
178        > api.set_active_mode(port')
179        """
180        raise NotImplementedError('set_active_mode must be implemented by subclass')
181
182    #############################
183    def set_active_logger_config(self, logger, config_name):
184        """Set the active logger config for the specified logger to
185        the specific logger_config name.
186        > api.set_active_logger_config('knud', 'knud->file/net/db')
187        """
188        raise NotImplementedError(
189            'set_active_logger_config must be implemented by subclass')
190
191    #############################
192
193    def quit(self):
194        """Execute any callbacks that were registered to run on quit."""
195        for (callback, kwargs) in self.quit_callbacks:
196            logging.debug('Executing quit callback: %s', callback)
197            callback(**kwargs)
198
199    #############################
200    # API method to register a callback. When the data store changes,
201    # methods that are registered via on_update() will be called so they
202    # can fetch updated results.
203    #############################
204    def on_update(self, callback, kwargs=None):
205        """Register a method to be called when current configs change."""
206        if kwargs is None:
207            kwargs = {}
208        self.update_callbacks.append((callback, kwargs))
209
210    #############################
211    def signal_update(self):
212        """Call the registered methods when current configs change."""
213        for (callback, kwargs) in self.update_callbacks:
214            logging.debug('Executing update callback: %s', callback)
215            callback(**kwargs)
216
217    #############################
218    # API method to register a callback. When the data store changes,
219    # methods that are registered via on_update() will be called so they
220    # can fetch updated results.
221    #############################
222    def on_load(self, callback, kwargs=None):
223        """Register a method to be called when new configs have been loaded."""
224        if kwargs is None:
225            kwargs = {}
226        self.load_callbacks.append((callback, kwargs))
227
228    #############################
229    def signal_load(self):
230        """Call the registered methods when new configs have been loaded."""
231        for (callback, kwargs) in self.load_callbacks:
232            logging.debug('Executing load callback: %s', callback)
233            callback(**kwargs)
234
235    #############################
236    # API method to register a callback. When the data store changes,
237    # methods that are registered via on_update() will be called so they
238    # can fetch updated results.
239    #############################
240    def on_quit(self, callback, kwargs=None):
241        """Register a method to be called when quit is signaled changes."""
242        if kwargs is None:
243            kwargs = {}
244        self.quit_callbacks.append((callback, kwargs))
245
246    ############################
247    # Methods for getting logger status data from API
248    ############################
249    def get_status(self, since_timestamp=None):
250        """Retrieve a dict of the most-recent status report from each
251        logger. If since_timestamp is specified, retrieve all status reports
252        since that time."""
253        raise NotImplementedError('get_status must be implemented by subclass')
254
255    ############################
256    # Methods for storing/retrieving messages from servers/loggers/etc.
257    ############################
258    # Logging levels corresponding to logging module levels
259    CRITICAL = logging.CRITICAL
260    ERROR = logging.ERROR
261    WARNING = logging.WARNING
262    INFO = logging.INFO
263    DEBUG = logging.DEBUG
264
265    ############################
266    def message_log(self, source, user, log_level, message):
267        """Timestamp and store the passed message."""
268        raise NotImplementedError('message_log must be implemented by subclass')
269
270    ############################
271    def get_message_log(self, source=None, user=None, log_level=sys.maxsize,
272                        since_timestamp=None):
273        """Retrieve log messages from source at or above log_level since
274        timestamp. If source is omitted, retrieve from all sources. If
275        log_level is omitted, retrieve at all levels. If since_timestamp is
276        omitted, only retrieve most recent message.
277        """
278        raise NotImplementedError('get_message_log must be implemented by subclass')
279
280    #############################
281    """Methods below are used to load/create/modify the data store's model
282  of a cruise."""
283    #############################
284
285    def load_configuration(self, configuration):
286        """Load a complete cruise configuration to the data store.
287        > api.load_configuration({ configuration })
288        """
289        raise NotImplementedError('load_configuration must be implemented by subclass')
290
291    #############################
292    # def add_cruise(self, cruise_id, start=None, end=None):
293    #   """Add a new cruise_id to the data store. Use methods below to build
294    #   it out.
295    #   > api.add_cruise('NBP1702', '2017-02-02', '2017-03-01')
296    #   """
297    #   raise NotImplementedError('add_cruise must be implemented by subclass')
298
299    #############################
300    def delete_configuration(self):
301        """Remove the specified cruise from the data store.
302        > api.delete_configuration()
303        """
304        raise NotImplementedError('delete_configuration must be implemented by subclass')
305
306    #############################
307    def add_mode(self, mode):
308        """Add a new mode to the OpenRVDAS configuration.
309        > api.add_mode('underway')
310        """
311        raise NotImplementedError('add_mode must be implemented by subclass')
312
313    #############################
314    def delete_mode(self, mode):
315        """Delete the named mode (and all its configs) from the
316        data store. If the deleted mode is the active mode, set
317        the active mode to the default mode.
318        > api.delete_mode('underway')
319        """
320        raise NotImplementedError('delete_mode must be implemented by subclass')
321
322    #############################
323    def add_logger(self, logger_id, logger_config):
324        """Add a new logger to the data store.
325
326        logger_config - a dict defining:
327          host - optional restriction on which host logger must run
328          configs - list of logger_config names
329        > api.add_logger(gyr2', { 'host_id': <host_id>, 'configs': [....] })
330        """
331        raise NotImplementedError('add_logger must be implemented by subclass')
332
333    #############################
334    def delete_logger(self, logger_id):
335        """Remove a logger and all its associated logger_configs from the data store.
336        > api.delete_logger(gyr2')
337        """
338        raise NotImplementedError('delete_logger must be implemented by subclass')
339
340    #############################
341    def add_logger_config(self, logger_config_name, logger_config_spec):
342        """Add a new logger config to the data store.
343        > api.add_logger_config('gyr2->net/file/db', { logger_config_spec })
344        """
345        raise NotImplementedError('add_config must be implemented by subclass')
346
347    #############################
348    def add_logger_config_to_logger(self, config, logger_id):
349        """Associate a config with a logger.
350        > api.add_logger_config_to_logger('gyr2->net/file/db', 'gyr2')
351        """
352        raise NotImplementedError('add_logger_config_to_logger must be implemented by subclass')
353
354    #############################
355    def add_logger_config_to_mode(self, config, logger_id, mode):
356        """Associate a config with a logger and mode.
357        > api.add_logger_config_to_mode('gyr2->net/file/db', 'gyr2', 'underway')
358        """
359        raise NotImplementedError('add_logger_config_to_mode must be implemented by subclass')
360
361    #############################
362    def delete_logger_config(self, config_id):
363        """Delete specified config from data store (and by extension,
364        from the mode and logger with which it is associated.
365        > api.delete_logger_config('gyr2->net/file/db')
366        """
367        raise NotImplementedError('delete_logger_config must be implemented by subclass')