You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/manual-wiki/extend.wiki
+31-32Lines changed: 31 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,79 +4,79 @@
4
4
5
5
This page describes how to extend Ocsigen's server. This can be used to create new ways to generate pages (like Apache modules), to filter and change the requests (for example, rewriting of URLS), to extend the syntax of the configuration file.
6
6
7
-
Remember to program your extensions in cooperative way using Lwt!
7
+
Remember to program your extensions in cooperative way using Lwt!
8
8
9
-
These features have been introduced in Ocsigen 0.6.0. The extension mechanism will be improved in the future to fit better the needs of developers. As very extensions have been written for now, all this is somewhat experimental, and we look forward to feedback from developers about missing features or problems.
9
+
These features have been introduced in Ocsigen 0.6.0. The extension mechanism will be improved in the future to fit better the needs of developers. As very extensions have been written for now, all this is somewhat experimental, and we look forward to feedback from developers about missing features or problems.
10
10
11
11
//Ocsigen is a collaborative project. Contributions are welcome. For example a proxy, a fastCGI module~ ...//
12
12
13
-
===Filtering the requests or writing a module to generate pages
13
+
===Filtering the requests or writing a module to generate pages
14
14
15
-
You can take as example the files {{{extensiontemplate.ml}}} or {{{staticmod.ml}}} from Ocsigen's distribution.
15
+
You can take as example the files {{{extensiontemplate.ml}}} or {{{staticmod.ml}}} from Ocsigen's distribution.
16
16
17
-
The type of request is {{{Extensions.request_info}}} (have a look at it in the interface of the module {{{Extensions}}}).
17
+
The type of request is {{{Extensions.request_info}}} (have a look at it in the interface of the module {{{Extensions}}}).
18
18
19
-
Each extensions loaded in the configuration file tries to handle the request and returns something of type {{{Extensions.answer}}}. If the page is not found by the extension ({{{Ext_not_found}}}), the following one will try to handle the request. If the page is found, the answer is {{{Ext_found r}}} where {{{r}}} has type {{{Extensions.result}}}. An extension can also modify the request before giving it to the next one (answer {{{Ext_continue_with of Extensions.request_info}}}).
19
+
Each extensions loaded in the configuration file tries to handle the request and returns something of type {{{Extensions.answer}}}. If the page is not found by the extension ({{{Ext_not_found}}}), the following one will try to handle the request. If the page is found, the answer is {{{Ext_found r}}} where {{{r}}} has type {{{Extensions.result}}}. An extension can also modify the request before giving it to the next one (answer {{{Ext_continue_with of Extensions.request_info}}}).
20
20
21
-
To write such an extension, just write a cmo or cma, and use the function Extensions.register_extension to register you extension. This function takes four functions as parameters:
22
-
* a function that will be called for each virtual server, generating two functions:
23
-
**one that will be called to generate the pages (it has type {{{string option -> request_info -> answer Lwt.t}}}), where the {{{string option}}} is the encoding for characters possibly specified in the configuration file,
24
-
**one to parse the configuration file (see next section).
25
-
*a function that will be called at the beginning of the initialisation phase (if you need to initialize your extension, otherwise, put the identity).
26
-
*a function that will be called at the end of the initialisation phase of the server (if you need to do something here, otherwise the identity function).
27
-
*a function that will create an error message from the exceptions that may be raised during the initialisation phase, and raise again all other exceptions. That function has type {{{exn -> string}}}. Use the raise function if you don't need any.
21
+
To write such an extension, just write a cmo or cma, and use the function Extensions.register_extension to register you extension. This function takes four functions as parameters:
22
+
* a function that will be called for each virtual server, generating two functions:
23
+
**one that will be called to generate the pages (it has type {{{string option -> request_info -> answer Lwt.t}}}), where the {{{string option}}} is the encoding for characters possibly specified in the configuration file,
24
+
**one to parse the configuration file (see next section).
25
+
*a function that will be called at the beginning of the initialisation phase (if you need to initialize your extension, otherwise, put the identity).
26
+
*a function that will be called at the end of the initialisation phase of the server (if you need to do something here, otherwise the identity function).
27
+
*a function that will create an error message from the exceptions that may be raised during the initialisation phase, and raise again all other exceptions. That function has type {{{exn -> string}}}. Use the raise function if you don't need any.
28
28
29
-
Example (from {{{staticmod.ml}}}):
29
+
Example (from {{{staticmod.ml}}}):
30
30
31
31
{{{
32
32
let _ = register_extension
33
-
((fun _ ->
34
-
let page_tree =
35
-
try
33
+
((fun _ ->
34
+
let page_tree =
35
+
try
36
36
find hostpattern
37
37
with Not_found ->
38
38
let n = new_pages_tree () in
39
39
add hostpattern n;
40
40
n
41
41
in
42
-
(gen page_tree,
42
+
(gen page_tree,
43
43
parse_config page_tree)),
44
44
start_init,
45
45
end_init,
46
46
raise)
47
47
}}}
48
48
49
-
While writing extensions, be very careful about site reloading. The initialisation phase will start again at each reloading, and the function you register will be called for each virtual at each reloading.
49
+
While writing extensions, be very careful about site reloading. The initialisation phase will start again at each reloading, and the function you register will be called for each virtual at each reloading.
50
50
51
-
===Filtering the outputs
51
+
===Filtering the outputs
52
52
It is also possible to create extensions that will filter the output of the server (for example to compress it). It is very similar to the previous one. Basically, use {{{Extensions.register_output_filter}}} instead of {{{Extensions.register_extension}}}. Have a look at the file {{{deflatemod.ml}}} for an example.
53
53
54
-
===Extending the configuration file
54
+
===Extending the configuration file
55
55
56
-
====Extending the configuration file for an extension
56
+
====Extending the configuration file for an extension
57
57
58
-
The parsing of Ocsigen's configuration file is using a very basic xml parser (module {{{Simplexmlparser}}}). The function to be registered by the {{{Extensions.register_extension}}} function takes two parameters: the path of the web site and the xml subtree.
58
+
The parsing of Ocsigen's configuration file is using a very basic xml parser (package {{{xml-light}}}). The function to be registered by the {{{Extensions.register_extension}}} function takes two parameters: the path of the web site and the xml subtree.
The module {{{Parseconfig}}} defines functions to parse strings or sizes (in bytes, GB etc).
69
+
The module {{{Parseconfig}}} defines functions to parse strings or sizes (in bytes, GB etc).
70
70
71
-
====Giving parameters to an extension
71
+
====Giving parameters to an extension
72
72
73
73
//Warning: This is experimental. Please report your experience if you use it.//
74
74
75
-
Extensions may take parameters in the configuration file. During the loading of the extension, the function {{{Extensions.get_config ()}}} returns the xml tree between {{{<extension>}}} and {{{</extension>}}} (or {{{<library>}}} and {{{</library>}}}). Write a parser for that tree.
75
+
Extensions may take parameters in the configuration file. During the loading of the extension, the function {{{Extensions.get_config ()}}} returns the xml tree between {{{<extension>}}} and {{{</extension>}}} (or {{{<library>}}} and {{{</library>}}}). Write a parser for that tree.
76
76
77
-
===Catching the request before it is fully read
77
+
===Catching the request before it is fully read
78
78
79
-
For some extensions of the Web server, it is necessary to catch the request before it has been fully read (especially before the body of the request has been read). For example it is the case if you want to write a (reverse) proxy.
79
+
For some extensions of the Web server, it is necessary to catch the request before it has been fully read (especially before the body of the request has been read). For example it is the case if you want to write a (reverse) proxy.
80
80
81
81
//Warning: This is experimental. Please report your experience if you use it.//
82
82
@@ -94,10 +94,9 @@ It takes as parameter a function of type
94
94
If you want to add your own commands for the server command pipe, do something like:
0 commit comments