octopi/library/tentacles/entity_registry.h

   1 #ifndef CLIENT_REGISTRY_CLASS
   2 #define CLIENT_REGISTRY_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : entity_registry                                                   *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2002-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/byte_array.h>
  20 #include <mathematics/chaos.h>
  21 #include <timely/time_stamp.h>
  22 #include <processes/safe_roller.h>
  23 #include <sockets/tcpip_stack.h>
  24
  25 namespace octopi {
  26
  27 class octopus_entity;
  28
  29 //! Provides a security model for the octopus.
  30 /*!
  31   Derived versions of this class can be hooked to an octopus to enforce
  32   a particular security model.
  33 */
  34
  35 class entity_registry
  36 {
  37 public:
  38   entity_registry();
  39   virtual ~entity_registry();
  40
  41   virtual bool authorized(const octopus_entity &entity) = 0;
  42     //!< returns true if the "entity" is a registered entity.
  43     /*!< this indicates that the entity is authorized to use this octopus'
  44     services. */
  45
  46   virtual bool locate_entity(const octopus_entity &entity,
  47           timely::time_stamp &last_active, basis::byte_array &verification) = 0;
  48     //!< retrieves the security records for the "entity", if any exist.
  49     /*!< true is returned on success and "last_active" is set to the entity's
  50     last time of activity and "verification" is set to the cilent's
  51     verification token from its login. */
  52
  53   virtual bool add_entity(const octopus_entity &entity,
  54           const basis::byte_array &verification) = 0;
  55     //!< adds the "entity" to the list of authorized users if allowed.
  56     /*!< note that this will still succeed if the entity is already present.
  57     the "verification" is used by the entity to prove its case for admittance,
  58     but if it has zero length, it's ignored.  true is returned if the entity
  59     was allowed to login or refresh its record.  false is returned if the
  60     entity was denied, possibly because of a bad or missing verification
  61     token. */
  62
  63   virtual bool refresh_entity(const octopus_entity &entity) = 0;
  64     //!< this should be used to refresh the entity's health record.
  65     /*!< it indicates that this entity is still functioning and should not
  66     be removed due to inactivity. */
  67
  68   virtual bool zap_entity(const octopus_entity &entity) = 0;
  69     //!< removes a "entity" if the entity can be found.
  70     /*!< true is returned if that "entity" existed. */
  71
  72   virtual basis::astring text_form() = 0;
  73     //!< prints out the contents of the entity registry.
  74
  75 private:
  76   processes::safe_roller *_sequencer;  //!< issues unique ids for entities.
  77   mathematics::chaos *_rando;  //!< issues random portions of ids.
  78   sockets::tcpip_stack *_stack;  //!< provides hostname and network info.
  79 };
  80
  81 //////////////
  82
  83 //! the blank_entity_registry can be used when security is not an issue.
  84 /*!
  85   it always assumes every entity is valid.  when the locate() method is
  86   invoked, a feel-good record is produced.
  87 */
  88
  89 class blank_entity_registry : public entity_registry
  90 {
  91 public:
  92   bool authorized(const octopus_entity &formal(entity)) { return true; }
  93   bool locate_entity(const octopus_entity &entity,
  94           timely::time_stamp &last_active, basis::byte_array &verification);
  95   bool add_entity(const octopus_entity &formal(entity),
  96           const basis::byte_array &formal(verification)) { return true; }
  97   bool refresh_entity(const octopus_entity &formal(entity)) { return true; }
  98   bool zap_entity(const octopus_entity &formal(entity)) { return true; }
  99   basis::astring text_form();
 100 };
 101
 102 } //namespace.
 103
 104 #endif
 105