aboutsummaryrefslogtreecommitdiff
path: root/web/apache/service
blob: c66332301987b501315a426631b1328746d47bae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
// file      : web/apache/service -*- C++ -*-
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

#ifndef WEB_APACHE_SERVICE
#define WEB_APACHE_SERVICE

#include <apr_pools.h>   // apr_pool_t
#include <apr_hooks.h>   // APR_HOOK_*

#include <httpd.h>       // request_rec, server_rec, HTTP_*, DECLINED
#include <http_config.h> // module, cmd_parms, ap_hook_*()

#include <map>
#include <memory>  // unique_ptr
#include <string>
#include <cassert>

#include <web/module>
#include <web/apache/log>
#include <web/apache/request>

namespace web
{
  namespace apache
  {
    // Apache has 3 configuration scopes: main server, virtual server, and
    // directory (location). It provides configuration scope-aware modules
    // with the ability to build a hierarchy of configuration contexts. Later,
    // when processing a request, Apache passes the appropriate directory
    // configuration context to the request handler.
    //
    // This Apache service implementation first makes a copy of the provided
    // (in the constructor below) module exemplar for each directory context.
    // It then initializes each of these "context exemplars" with the (merged)
    // set of configuration options. Finally, when handling a request, it
    // copies the corresponding "context exemplar" to create the "handling
    // instance". Note that the "context exemplars" are create before the
    // provided exemplar is initialized. As a result, it is possible to detect
    // if the module's copy constructor is used to create a "context exemplar"
    // or a "handling instance".
    //
    class service: ::module
    {
    public:
      // Note that the module exemplar is stored by-reference.
      //
      template <typename M>
      service (const std::string& name, M& exemplar)
          : ::module
            {
              STANDARD20_MODULE_STUFF,
              nullptr,
              nullptr,
              nullptr,
              nullptr,
              nullptr,
              &register_hooks<M>
            },
            name_ (name),
            exemplar_ (exemplar)
      {
        init_directives ();

        // Set configuration context management hooks.
        //
        // The overall process of building the configuration hierarchy for a
        // module is as follows:
        //
        // 1. Apache creates directory and server configuration contexts for
        //    scopes containing module-defined directives by calling the
        //    create_{server,dir}_context() callback functions. For directives
        //    at the server scope the special directory context is created as
        //    well.
        //
        // 2. Apache calls parse_option() function for each module-defined
        //    directive. The function parses the directives and places the
        //    resulting options into the corresponding configuration context.
        //    It also establishes the directory-server contexts relations.
        //
        // 3. Apache calls merge_server_context() function for each virtual
        //    server. The function complements virtual server context options
        //    with the ones from the main server.
        //
        // 4. Apache calls config_finalizer() which complements the directory
        //    contexts options with the ones from the enclosing servers.
        //
        // 5. Apache calls worker_initializer() which creates module exemplar
        //    for each directory configuration context having
        //    'SetHandler <mod_name>' directive in effect for it.
        //
        // References:
        //   http://www.apachetutor.org/dev/config
        //   http://httpd.apache.org/docs/2.4/developer/modguide.html
        //   http://wiki.apache.org/httpd/ModuleLife
        //
        create_server_config = &create_server_context;
        create_dir_config = &create_dir_context;
        merge_server_config = &merge_server_context<M>;

        // instance<M> () is invented to delegate processing from apache
        // request handler C function to the service non static member
        // function. This appoach resticts number of service objects per
        // specific module implementation class with just one instance.
        //
        service*& srv (instance<M> ());
        assert (srv == nullptr);
        srv = this;
      }

      ~service ()
      {
        delete [] cmds;
      }

    private:
      template <typename M>
      static service*&
      instance () noexcept
      {
        static service* instance;
        return instance;
      }

      template <typename M>
      static void
      register_hooks (apr_pool_t*) noexcept
      {
        // The config_finalizer() function is called at the end of Apache
        // server configuration parsing.
        //
        ap_hook_post_config (&config_finalizer<M>, NULL, NULL, APR_HOOK_LAST);

        // The worker_initializer() function is called right after Apache
        // worker process is started. Called for every new process spawned.
        //
        ap_hook_child_init (
          &worker_initializer<M>, NULL, NULL, APR_HOOK_LAST);

        // The request_handler () function is called for each client request.
        //
        ap_hook_handler (&request_handler<M>, NULL, NULL, APR_HOOK_LAST);
      }

      template <typename M>
      static int
      config_finalizer (apr_pool_t*, apr_pool_t*, apr_pool_t*, server_rec* s)
        noexcept
      {
        instance<M> ()->finalize_config (s);
        return OK;
      }

      template <typename M>
      static void
      worker_initializer (apr_pool_t*, server_rec* s) noexcept
      {
        auto srv (instance<M> ());
        log l (s, srv);
        srv->template init_worker<M> (l);
      }

      template <typename M>
      static int
      request_handler (request_rec* r) noexcept;

    private:

      // Reflects the allowability of the request handling in the specific
      // configuration scope.
      //
      enum class request_handling
      {
        // Configuration scope has 'SetHandler <mod_name>' directive
        // specified. The module allowed to handle a request in the scope.
        //
        allowed,

        // Configuration scope has 'SetHandler <other_mod_name>|None'
        // directive specified. The module disallowed to handle a request in
        // the scope.
        //
        disallowed,

        //
        // Note that if there are several SetHandler directives specified
        // in the specific scope, then the latest one takes the precedence.

        // Configuration scope has no SetHandler directive specified. The
        // request handling allowability is established by the enclosing
        // scopes.
        //
        inherit
      };

      // Our representation of the Apache configuration context.
      //
      // The lifetime of this object is under the control of the Apache API,
      // which treats it as a raw sequence of bytes. In order not to tinker
      // with the C-style structures and APR memory pools, we will keep it a
      // (C++11) POD type with just the members required to maintain the
      // context hierarchy.
      //
      // We will then use the pointers to these context objects as keys in
      // maps to (1) the corresponding application-level option lists during
      // the configuration cycle and to (2) the corresponding module exemplar
      // during the HTTP request handling phase. We will also use the same
      // type for both directory and server configuration contexts.
      //
      struct context
      {
        // Outer (server) configuration context for the directory
        // configuration context, NULL otherwise.
        //
        context* server = nullptr;

        // If module directives appear directly in the server configuration
        // scope, Apache creates a special directory context for them. This
        // context appears at the same hierarchy level as the user-defined
        // directory contexts of the same server scope.
        //
        bool special;

        // Request handling allowability for the corresponding configuration
        // scope.
        //
        request_handling handling = request_handling::inherit;

        // Create the server configuration context.
        //
        context (): special (false) {}

        // Create the directory configuration context. Due to the Apache API
        // implementation details it is not possible to detect the enclosing
        // server configuration context at the time of directory context
        // creation. As a result, the server member is set by the module's
        // parse_option() function.
        //
        context (bool s): special (s) {}

        // Ensure the object is only destroyed by Apache.
        //
        ~context () = delete;
      };

      static context*
      context_cast (void* config) noexcept
      {return static_cast<context*> (config);}

    private:
      void
      init_directives ();

      // Create the server configuration context. Called by the Apache API
      // whenever a new object of that type is required.
      //
      static void*
      create_server_context (apr_pool_t*, server_rec*) noexcept;

      // Create the server directory configuration context. Called by the
      // Apache API whenever a new object of that type is required.
      //
      static void*
      create_dir_context (apr_pool_t*, char* dir) noexcept;

      template <typename M>
      static void*
      merge_server_context (apr_pool_t*, void* enclosing, void* enclosed)
        noexcept
      {
        instance<M> ()->complement (
          context_cast (enclosed), context_cast (enclosing));

        return enclosed;
      }

      static const char*
      parse_option (cmd_parms* parms, void* conf, const char* args) noexcept;

      const char*
      add_option (context*, const char* name, optional<std::string> value);

      void
      finalize_config (server_rec*);

      void
      clear_config ();

      // Complement the enclosed context with options of the enclosing one.
      // If the 'handling' member of the enclosed context is set to
      // request_handling::inherit value, assign it a value from the enclosing
      // context.
      //
      void
      complement (context* enclosed, context* enclosing);

      template <typename M>
      void
      init_worker (log&);

      template <typename M>
      int
      handle (request&, const context*, log&) const;

    private:
      std::string name_;
      module& exemplar_;
      option_descriptions option_descriptions_;

      // The context objects pointed by the key can change during the
      // configuration phase.
      //
      using options = std::map<context*, name_values>;
      options options_;

      // The context objects pointed by the key can not change during the
      // request handling phase.
      //
      using exemplars = std::map<const context*, std::unique_ptr<module>>;
      exemplars exemplars_;

      bool options_parsed_ = false;
      bool version_logged_ = false;
    };
  }
}

#include <web/apache/service.txx>

#endif // WEB_APACHE_SERVICE