From be1c7e50e1e8809ea56f2c9d472eccd8ffd73a97 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 04:57:58 +0200 Subject: Adding upstream version 1.44.3. Signed-off-by: Daniel Baumann --- .../h2o/libh2o/srcdoc/configure/file_directives.mt | 244 +++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 web/server/h2o/libh2o/srcdoc/configure/file_directives.mt (limited to 'web/server/h2o/libh2o/srcdoc/configure/file_directives.mt') diff --git a/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt new file mode 100644 index 00000000..b56de065 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt @@ -0,0 +1,244 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "File Directives")->(sub { + +

+This document describes the configuration directives of the file handler - a handler that for serving static files. +

+

+Two directives: file.dir and file.file are used to define the mapping. +Other directives modify the behavior of the mappings defined by the two. +

+ +{directive}->( + name => "file.custom-handler", + levels => [ qw(global host path) ], + desc => q{The directive maps extensions to a custom handler (e.g. FastCGI).}, +)->(sub { +?> +

+The directive accepts a mapping containing configuration directives that can be used at the extension level, together with a property named extension specifying a extension (starting with .) or a sequence of extensions to which the directives should be applied. +Only one handler must exist within the directives. +

+{example}->('Mapping PHP files to FastCGI', <<'EOT') +file.custom-handler: + extension: .php + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix + +EOT +?> +? }) + +{directive}->( + name => "file.dir", + levels => [ qw(path) ], + desc => q{The directive specifies the directory under which should be served for the corresponding path.}, + see_also => render_mt(<file.dirlisting, +file.file, +file.index +EOT +)->(sub { +?> +{example}->('Serving files under different paths', <<'EOT') +paths: + "/": + file.dir: /path/to/doc-root + "/icons": + file.dir: /path/to/icons-dir +EOT +?> +? }) + +{directive}->( + name => "file.dirlisting", + levels => [ qw(global host path) ], + default => 'file.dirlisting: OFF', + desc => <<'EOT', +A boolean flag (OFF, or ON) specifying whether or not to send the directory listing in case none of the index files exist. +EOT + see_also => render_mt(<file.dir +EOT +)->(sub {}); + +$ctx->{directive}->( + name => "file.etag", + levels => [ qw(global host path) ], + default => 'file.etag: ON', + desc => <<'EOT', +A boolean flag (OFF, or ON) specifying whether or not to send etags. +EOT +)->(sub {}); +?> + +{directive}->( + name => "file.file", + levels => [ qw(path) ], + desc => q{The directive maps a path to a specific file.}, + see_also => render_mt(<file.dir +EOT + since => '2.0', +)->(sub { +?> +{example}->('Mapping a path to a specific file', <<'EOT') +paths: + /robots.txt: + file.file: /path/to/robots.txt +EOT +?> +? }) + +{directive}->( + name => "file.index", + levels => [ qw(global host path) ], + default => "file.index: [ 'index.html', 'index.htm', 'index.txt' ]", + desc => q{Specifies the names of the files that should be served when the client sends a request against the directory.}, + see_also => render_mt(<file.dir +EOT +)->(sub { +?> +

+The sequence of filenames are searched from left to right, and the first file that existed is sent to the client. +

+? }) + +{directive}->( + name => "file.mime.addtypes", + levels => [ qw(global host path) ], + see_also => render_mt(<<'EOT'), +compress, +http2-casper, +http2-reprioritize-blocking-assets +EOT + desc => q{The directive modifies the MIME mappings by adding the specified MIME type mappings.}, +)->(sub { +?> +{example}->('Adding MIME mappings', <<'EOT') +file.mime.addtypes: + "application/javascript": ".js" + "image/jpeg": [ ".jpg", ".jpeg" ] +EOT +?> +

+The default mappings is hard-coded in lib/handler/mimemap/defaults.c.h. +

+

+It is also possible to set certain attributes for a MIME type. +The example below maps .css files to text/css type, setting is_compressible flag to ON and priority to highest. +

+ +{example}->('Setting MIME attributes', <<'EOT') +file.mime.settypes: + "text/css": + extensions: [".css"] + is_compressible: yes + priority: highest +EOT +?> + +

+Following attributes are recognized. +

+ + +
AttributePossible ValuesDescription +
is_compressibleON, OFFif content is compressible +
priorityhighest, normalsend priority of the content +
+ +

+The priority attribute affects how the HTTP/2 protocol implementation handles the request. +For detail, please refer to the HTTP/2 directives listed in the see also section below. +By default, mime-types for CSS and JavaScript files are the only ones that are given highest priority. +

+ +? }) + +{directive}->( + name => "file.mime.removetypes", + levels => [ qw(global host path) ], + desc => q{Removes the MIME mappings for specified extensions supplied as a sequence of extensions.}, +)->(sub { +?> +{example}->('Removing MIME mappings', <<'EOT') +file.mime.removetypes: [ ".jpg", ".jpeg" ] +EOT +?> +? }) + +{directive}->( + name => "file.mime.setdefaulttype", + levels => [ qw(global host path) ], + default => q{file.mime.setdefaulttype: "application/octet-stream"}, + desc => q{Sets the default MIME-type that is used when an extension does not exist in the MIME mappings}, +)->(sub {}) +?> + +{directive}->( + name => "file.mime.settypes", + levels => [ qw(global host path) ], + desc => q{Resets the MIME mappings to given mapping.}, +)->(sub { +?> +{example}->('Resetting the MIME mappings to minimum', <<'EOT') +file.mime.settypes: + "text/html": [ ".html", ".htm" ] + "text/plain": ".txt" +EOT +?> +? }) + +{directive}->( + name => "file.send-compressed", + levels => [ qw(global host path) ], + default => q{file.send-compressed: OFF}, + see_also => render_mt(<<'EOT'), +compress +EOT + since => '2.0', + desc => <<'EOT', +A flag indicating how a pre-compressed file should be served. +EOT +)->(sub { +?> +

+If set to ON, the handler looks for a file with .br or .gz appended and sends the file, if the client is capable of transparently decoding a brotli or gzip-encoded response. +For example, if a client requests a file named index.html with Accept-Encoding: gzip header and if index.html.gz exists, the .gz file is sent as a response together with a Content-Encoding: gzip response header. +

+

+If set to OFF, the handler always serves the file specified by the client. +

+

+Starting from version 2.2, gunzip is also supported. +If set, the handler acts identical to when the value was set to ON. +In addition, the handler will send an uncompressed response by dynamically decompressing the .gz file if the client and the server failed to agree on using a pre-compressed file as the response and if a non-compressed file was not found. +The option is useful when conserving disk space is important; it is possible to remove the uncompressed files in place for gzipped ones. +

+? }) + +{directive}->( + name => "file.send-gzip", + levels => [ qw(global host path) ], + desc => <<'EOT', +Obsoleted in 2.0. +Synonym of file.send-compressed. +EOT +)->(sub {}) +?> + +? }) -- cgit v1.2.3