auth_srv.h 8.31 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

// $Id$

#ifndef __AUTH_SRV_H
#define __AUTH_SRV_H 1

JINMEI Tatuya's avatar
cleanup    
JINMEI Tatuya committed
20
21
#include <string>

22
#include <cc/data.h>
23
#include <config/ccsession.h>
24

25
26
27
28
29
30
namespace isc {
namespace dns {
class InputBuffer;
class Message;
class MessageRenderer;
}
31
32
33
34

namespace xfr {
class AbstractXfroutClient;
};
35
36
}

37
38
namespace asio_link {
class IOMessage;
39
40
}

41
42
/// \brief The implementation class for the \c AuthSrv class using the pimpl
/// idiom.
43
class AuthSrvImpl;
44

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
/// \brief The authoritative nameserver class.
///
/// \c AuthSrv is a concrete class that implements authoritative DNS server
/// protocol processing.
/// An \c AuthSrv object is primarily responsible for handling incoming DNS
/// requests: It parses the request and dispatches subsequent processing to
/// the corresponding module (which may be an internal library or a separate
/// process) depending on the request type.  For normal queries, the
/// \c AuthSrv object searches configured data sources for the answer to the
/// query, and builds a response containing the answer.
///
/// This class uses the "pimpl" idiom, and hides detailed implementation
/// through the \c impl_ pointer (which points to an instance of the
/// \c AuthSrvImpl class).  An \c AuthSrv object is supposed to exist for quite
/// a long period, and only a few \c AuthSrv objects will be created (in fact,
/// in this current implementation there will only be one object), so the
/// construction overhead of this approach should be acceptable.
///
/// The design of this class is still in flux.  It's quite likely to change
/// in future versions.
65
class AuthSrv {
66
67
68
    ///
    /// \name Constructors, Assignment Operator and Destructor.
    ///
69
70
    /// Note: The copy constructor and the assignment operator are
    /// intentionally defined as private.
71
72
73
74
    //@{
private:
    AuthSrv(const AuthSrv& source);
    AuthSrv& operator=(const AuthSrv& source);
75
public:
76
77
78
79
80
81
82
    /// The constructor.
    ///
    /// \param use_cache Whether to enable hot spot cache for lookup results.
    /// \param xfrout_client Communication interface with a separate xfrout
    /// process.  It's normally a reference to an xfr::XfroutClient object,
    /// but can refer to a local mock object for testing (or other
    /// experimental) purposes.
83
84
    AuthSrv(const bool use_cache,
            isc::xfr::AbstractXfroutClient& xfrout_client);
85
    ~AuthSrv();
86
    //@}
Jeremy C. Reed's avatar
Jeremy C. Reed committed
87
    /// \return \c true if the \a message contains a response to be returned;
88
    /// otherwise \c false.
89
    bool processMessage(const asio_link::IOMessage& io_message,
90
                        isc::dns::Message& message,
91
                        isc::dns::MessageRenderer& response_renderer);
92
93
94
95
96
97
98
99
100
101
102
103
104
105

    /// \brief Enable or disable verbose logging.
    ///
    /// This method never throws an exception.
    ///
    /// \param on \c true to enable verbose logging; \c false to disable
    /// verbose logging.
    void setVerbose(const bool on);

    /// \brief Returns the logging verbosity of the \c AuthSrv object.
    ///
    /// This method never throws an exception.
    ///
    /// \return \c true if verbose logging is enabled; otherwise \c false.
106
    bool getVerbose() const;
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

    /// \brief Updates the data source for the \c AuthSrv object.
    ///
    /// This method installs or replaces the data source that the \c AuthSrv
    /// object refers to for query processing.
    /// Although the method name is generic, the only thing it does is to
    /// update the data source information.
    /// If there is a data source installed, it will be replaced with the
    /// new one.
    ///
    /// In the current implementation, the SQLite data source is assumed.
    /// The \c config parameter will simply be passed to the initialization
    /// routine of the \c Sqlite3DataSrc class.
    ///
    /// On success this method returns a data \c Element (in the form of a
    /// pointer like object) indicating the successful result,
    /// i.e., {"result": [0]}.
    /// Otherwise, it returns a data \c Element explaining the error:
    /// {"result": [1, <error-description>]}.
    ///
    /// This method is mostly exception free (error conditions are represented
    /// via the return value).  But it may still throw a standard exception
    /// if memory allocation fails inside the method.
    /// When a standard exception is thrown or an implementation specific
    /// exception is triggered and caught internally, this function provides
    /// the strong exception guarantee: Unless everything succeeds, currently
    /// installed data source (if any) won't be replaced.
    ///
    /// \param config An immutable pointer-like object to a data \c Element,
    /// possibly containing the data source information to be used.
    /// \return An immutable pointer-like object to a data \c Element
    /// containing the result of the update operation.
139
    isc::data::ConstElementPtr updateConfig(isc::data::ConstElementPtr config);
140

Jeremy C. Reed's avatar
Jeremy C. Reed committed
141
    /// \brief Returns the command and configuration session for the
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
    /// \c AuthSrv.
    ///
    /// This method never throws an exception.
    ///
    /// \return A pointer to \c ModuleCCSession object stored in the
    /// \c AuthSrv object.  In this implementation it could be NULL.
    isc::config::ModuleCCSession* getConfigSession() const;

    /// \brief Set the command and configuration session for the \c AuthSrv.
    ///
    /// Note: this interface is tentative.  We'll revisit the ASIO and session
    /// frameworks, at which point the session will probably be passed on
    /// construction of the server.
    /// In the current implementation, this method is expected to be called
    /// exactly once as part of initialization.  If this method is called
    /// multiple times, previously specified session is silently overridden.
    ///
    /// This method never throws an exception.
    ///
    /// \param config_session A pointer to \c ModuleCCSession object to receive
    /// control commands and configuration updates.
163
164
    void setConfigSession(isc::config::ModuleCCSession* config_session);

JINMEI Tatuya's avatar
JINMEI Tatuya committed
165
166
167
    /// \brief Set or update the size (number of slots) of hot spot cache.
    ///
    /// If the specified size is 0, it means the size will be unlimited.
168
169
    /// The specified size is recorded even if the cache is disabled; the
    /// new size will be effective when the cache is enabled.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
170
171
172
173
174
175
176
177
    ///
    /// This method never throws an exception.
    ///
    /// \param slots The number of cache slots.
    void setCacheSlots(const size_t slots);

    /// \brief Get the current size (number of slots) of hot spot cache.
    ///
178
179
    /// It always returns the recorded size regardless of the cache is enabled.
    ///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
180
181
182
183
184
    /// This method never throws an exception.
    ///
    /// \return The current number of cache slots.
    size_t getCacheSlots() const;

185
186
    /// \brief Set the communication session with a separate process for
    /// outgoing zone transfers.
187
188
189
190
191
192
193
194
195
196
197
198
    ///
    /// Note: this interface is tentative.  We'll revisit the ASIO and session
    /// frameworks, at which point the session will probably be passed on
    /// construction of the server.
    ///
    /// \param xfrin_session A Session object over which NOTIFY message
    /// information is exchanged with a XFRIN handler.
    /// The session must be established before setting in the server
    /// object.
    /// Ownership isn't transferred: the caller is responsible for keeping
    /// this object to be valid while the server object is working and for
    /// disconnecting the session and destroying the object when the server
199
    /// is shutdown.
200
201
    ///
    void setXfrinSession(isc::cc::AbstractSession* xfrin_session);
202
private:
203
    AuthSrvImpl* impl_;
204
205
206
207
};

#endif // __AUTH_SRV_H

JINMEI Tatuya's avatar
cleanup    
JINMEI Tatuya committed
208
209
210
// Local Variables: 
// mode: c++
// End: