src/acl/Checklist.h

   1 /*
   2  * $Id$
   3  *
   4  *
   5  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   6  * ----------------------------------------------------------
   7  *
   8  *  Squid is the result of efforts by numerous individuals from
   9  *  the Internet community; see the CONTRIBUTORS file for full
  10  *  details.   Many organizations have provided support for Squid's
  11  *  development; see the SPONSORS file for full details.  Squid is
  12  *  Copyrighted (C) 2001 by the Regents of the University of
  13  *  California; see the COPYRIGHT file for full details.  Squid
  14  *  incorporates software developed and/or copyrighted by other
  15  *  sources; see the CREDITS file for full details.
  16  *
  17  *  This program is free software; you can redistribute it and/or modify
  18  *  it under the terms of the GNU General Public License as published by
  19  *  the Free Software Foundation; either version 2 of the License, or
  20  *  (at your option) any later version.
  21  *
  22  *  This program is distributed in the hope that it will be useful,
  23  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  *  GNU General Public License for more details.
  26  *
  27  *  You should have received a copy of the GNU General Public License
  28  *  along with this program; if not, write to the Free Software
  29  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  30  *
  31  */
  32
  33 #ifndef SQUID_ACLCHECKLIST_H
  34 #define SQUID_ACLCHECKLIST_H
  35
  36 #include "acl/Acl.h"
  37
  38 /// ACL checklist callback
  39 typedef void ACLCB(allow_t, void *);
  40
  41 /** \ingroup ACLAPI
  42     Base class for maintaining Squid and transaction state for access checks.
  43         Provides basic ACL checking methods. Its only child, ACLFilledChecklist,
  44         keeps the actual state data. The split is necessary to avoid exposing
  45     all ACL-related code to virtually Squid data types. */
  46 class ACLChecklist
  47 {
  48
  49 public:
  50
  51     /**
  52      * State class.
  53      * This abstract class defines the behaviour of
  54      * async lookups - which can vary for different ACL types.
  55      * Today, every state object must be a singleton.
  56      * See NULLState for an example.
  57      *
  58      \note *no* state should be stored in the state object,
  59      * they are used to change the behaviour of the checklist, not
  60      * to hold information. If you need to store information in the
  61      * state object, consider subclassing ACLChecklist, converting it
  62      * to a composite, or changing the state objects from singletons to
  63      * refcounted objects.
  64      */
  65
  66     class AsyncState
  67     {
  68
  69     public:
  70         virtual void checkForAsync(ACLChecklist *) const = 0;
  71         virtual ~AsyncState() {}
  72
  73     protected:
  74         void changeState (ACLChecklist *, AsyncState *) const;
  75     };
  76
  77     class NullState : public AsyncState
  78     {
  79
  80     public:
  81         static NullState *Instance();
  82         virtual void checkForAsync(ACLChecklist *) const;
  83         virtual ~NullState() {}
  84
  85     private:
  86         static NullState _instance;
  87     };
  88
  89
  90 public:
  91     ACLChecklist();
  92     virtual ~ACLChecklist();
  93
  94     /**
  95      * Trigger off a non-blocking access check for a set of *_access options..
  96      * The callback specified will be called with true/false
  97      * when the results of the ACL tests are known.
  98      */
  99     void nonBlockingCheck(ACLCB * callback, void *callback_data);
 100
 101     /**
 102      * Trigger a blocking access check for a set of *_access options.
 103      *
 104      * ACLs which cannot be satisfied directly from available data are ignored.
 105      * This means any proxy_auth, external_acl, DNS lookups, Ident lookups etc
 106      * which have not already been performed and cached will not be checked.
 107      *
 108      * If there is no access list to check the default is to return ALLOWED.
 109      * However callers should perform their own check and default based on local
 110      * knowledge of the ACL usage rather than depend on this default.
 111      * That will also save on work setting up ACLChecklist fields for a no-op.
 112      *
 113      * \retval ACCESS_DUNNO     Unable to determine any result
 114      * \retval ACCESS_ALLOWED   Access Allowed
 115      * \retval ACCESS_DENIED    Access Denied
 116      */
 117     allow_t const & fastCheck();
 118
 119     /**
 120      * A version of fastCheck() for use when there is a one-line set of ACLs
 121      * to be tested and a match determins the result action to be done.
 122      *
 123      * \retval ACCESS_DUNNO     Unable to determine any result
 124      * \retval ACCESS_ALLOWED   ACLs all matched
 125      */
 126     allow_t const & fastCheck(const ACLList * list);
 127
 128     bool asyncInProgress() const;
 129     void asyncInProgress(bool const);
 130
 131     bool finished() const;
 132     void markFinished();
 133
 134     const allow_t &currentAnswer() const { return allow_; }
 135     void currentAnswer(const allow_t &newAnswer) { allow_ = newAnswer; }
 136
 137     void changeState(AsyncState *);
 138     AsyncState *asyncState() const;
 139
 140     // XXX: ACLs that need request or reply have to use ACLFilledChecklist and
 141     // should do their own checks so that we do not have to povide these two
 142     // for ACL::checklistMatches to use
 143     virtual bool hasRequest() const = 0;
 144     virtual bool hasReply() const = 0;
 145
 146 protected:
 147     virtual void checkCallback(allow_t answer);
 148 private:
 149     void checkAccessList();
 150     void checkForAsync();
 151
 152 public:
 153     const acl_access *accessList;
 154
 155     ACLCB *callback;
 156     void *callback_data;
 157
 158     /**
 159      * Attempt to check the current checklist against current data.
 160      * This is the core routine behind all ACL test routines.
 161      * As much as possible of current tests are performed immediately
 162      * and the result is maybe delayed to wait for async lookups.
 163      *
 164      * When all tests are done callback is presented with one of:
 165      *  - ACCESS_ALLOWED     Access explicitly Allowed
 166      *  - ACCESS_DENIED      Access explicitly Denied
 167      */
 168     void matchNonBlocking();
 169
 170 private: /* internal methods */
 171     void preCheck();
 172     void matchAclList(const ACLList * list, bool const fast);
 173
 174     bool async_;
 175     bool finished_;
 176     allow_t allow_;
 177     AsyncState *state_;
 178
 179     bool checking_;
 180     bool checking() const;
 181     void checking (bool const);
 182
 183     bool lastACLResult_;
 184     bool callerGone();
 185
 186 public:
 187     bool lastACLResult(bool x) { return lastACLResult_ = x; }
 188
 189     bool lastACLResult() const { return lastACLResult_; }
 190 };
 191
 192 #endif /* SQUID_ACLCHECKLIST_H */