docs: directory listing format [skip ci]
refs #151
Diff
docs/content/configuration/command-line-arguments.md | 9 ++-
docs/content/configuration/config-file.md | 7 +-
docs/content/configuration/environment-variables.md | 3 +-
docs/content/features/directory-listing.md | 68 ++++++++++++++++++---
4 files changed, 76 insertions(+), 11 deletions(-)
@@ -39,11 +39,11 @@ OPTIONS:
Server TOML configuration file path [env: SERVER_CONFIG_FILE=]
-j, --cors-allow-headers <cors-allow-headers>
Specify an optional CORS list of allowed headers separated by comas. Default "origin, content-type". It
Specify an optional CORS list of allowed headers separated by commas. Default "origin, content-type". It
requires `--cors-allow-origins` to be used along with [env: SERVER_CORS_ALLOW_HEADERS=] [default: origin,
content-type]
-c, --cors-allow-origins <cors-allow-origins>
Specify an optional CORS list of allowed origin hosts separated by comas. Host ports or protocols aren't
Specify an optional CORS list of allowed origin hosts separated by commas. Host ports or protocols aren't
being checked. Use an asterisk (*) to allow any host [env: SERVER_CORS_ALLOW_ORIGINS=] [default: ]
--cors-expose-headers <cors-expose-headers>
Specify an optional CORS list of exposed headers separated by commas. Default "origin, content-type". It
@@ -52,6 +52,9 @@ OPTIONS:
-z, --directory-listing <directory-listing>
Enable directory listing for all requests ending with the slash character (‘/’) [env:
SERVER_DIRECTORY_LISTING=] [default: false]
--directory-listing-format <directory-listing-format>
Specify a content format for directory listing entries. Formats supported: "html" or "json". Default "html"
[env: SERVER_DIRECTORY_LISTING_FORMAT=] [default: html] [possible values: Html, Json]
--directory-listing-order <directory-listing-order>
Specify a default code number to order directory listing entries per `Name`, `Last modified` or `Size`
attributes (columns). Code numbers supported: 0 (Name asc), 1 (Name desc), 2 (Last modified asc), 3 (Last
@@ -95,7 +98,7 @@ OPTIONS:
--page50x <page50x>
HTML file path for 50x errors. If the path is not specified or simply doesn't exist then the server will use
a generic HTML error message [env: SERVER_ERROR_PAGE_50X=] [default: ./public/50x.html]
-p, --port <port> Host port [env: SERVER_PORT=] [default: 80]
-p, --port <port> Host port [env: SERVER_PORT=] [default: 80]
--redirect-trailing-slash <redirect-trailing-slash>
Check for a trailing slash in the requested directory URI and redirect permanently (308) to the same path
with a trailing slash suffix if it is missing [env: REDIRECT_TRAILING_SLASH=] [default: true]
@@ -43,8 +43,13 @@ cors-allow-headers = ""
#### Directory listing
directory-listing = false
#### Directory listing sorting code
directory-listing-order = 6
#### Directory listing content format ("html" or "json")
directory-listing-format = "html"
#### Basich Authentication
basic-auth = ""
@@ -99,7 +104,7 @@ So they are equivalent to each other **except** for the `-w, --config-file` opti
The TOML `[advanced]` section is intended for more complex features.
For example [Custom HTTP Headers](../features/custom-http-headers.md).
For example [Custom HTTP Headers](../features/custom-http-headers.md) or [Custom URL Redirects](../features/url-redirects.md).
### Precedence
@@ -72,6 +72,9 @@ Enable directory listing for all requests ending with the slash character (‘/
### SERVER_DIRECTORY_LISTING_ORDER
Specify a default code number to order directory listing entries per `Name`, `Last modified` or `Size` attributes (columns). Code numbers supported: `0` (Name asc), `1` (Name desc), `2` (Last modified asc), `3` (Last modified desc), `4` (Size asc), `5` (Size desc). Default `6` (unordered).
### SERVER_DIRECTORY_LISTING_FORMAT
Specify a content format for the directory listing entries. Formats supported: `html` or `json`. Default `html`
### SERVER_SECURITY_HEADERS
Enable security headers by default when HTTP/2 feature is activated. Headers included: `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years max-age), `X-Frame-Options: DENY`, `X-XSS-Protection: 1; mode=block` and `Content-Security-Policy: frame-ancestors 'self'`. Default `false` (disabled).
@@ -30,32 +30,32 @@ Sorting by `Name`, `Last modified` and `Size` is enabled as clickable columns wh
You can also use the `sort` query parameter to sort manually by certain attributes from URI. E.g `https://localhost/?sort=5`.
## Sorting by default
### Sorting by default
Sometimes one wants to sort by certain attribute but by **default**. In that case, the default ascending or descending ordering of files/dirs by their attributes is provided by the numeric `--directory-listing-order` option or the equivalent [SERVER_DIRECTORY_LISTING_ORDER](./../configuration/environment-variables.md#server_directory_listing_order) env.
Sometimes one wants to sort by a certain attribute but by **default**. In that case, the default ascending or descending ordering of files/dirs by their attributes is provided by the numeric `--directory-listing-order` option or the equivalent [SERVER_DIRECTORY_LISTING_ORDER](./../configuration/environment-variables.md#server_directory_listing_order) env.
To do so you have to pass a [code sorting number](#code-numbers-for-sorting). E.g `--directory-listing-order=2`.
## Code numbers for sorting
### Code numbers for sorting
Below are the possible number code values for sorting or ordering which are grouped by attribute.
### Name
#### Name
- `0`: Ascending
- `1`: Descending
### Last modified
#### Last modified
- `2`: Ascending
- `3`: Descending
### Size
#### Size
- `4`: Ascending
- `5`: Descending
### Default
#### Default
- `6`: Unordered
@@ -73,3 +73,57 @@ static-web-server \
# E.g Sorting file/dir names in descending order
--directory-listing-order 1
```
## Output format
**`SWS`** provides support for specifying an output format either HTML (default) or JSON for the directory listing entries via the string `--directory-listing-format` option or the equivalent [SERVER_DIRECTORY_LISTING_FORMAT](./../configuration/environment-variables.md#server_directory_listing_format) env.
!!! tip "Tips"
- The `--directory-listing-format` option depends on `--directory-listing` to be enabled.
### HTML format
This is the default format when `--directory-listing` is enabled.
### JSON format
The JSON format used is shown below for directories and files. Note that the `size` attribute is only available for files and the `mtime` value is UTC-based.
```json
[
{
"name": "my-directory",
"type": "directory",
"mtime": "2022-10-07T00:53:50Z"
},
{
"name": "my_file.tar.gz",
"type": "file",
"mtime": "2022-09-27T22:44:34Z",
"size": 332
}
]
```
Here is an example of serving the directory listing in JSON format.
```sh
static-web-server \
-p=8787 -d=tests/fixtures/public -g=trace \
--directory-listing=true \
--directory-listing-format="json"
```
And below and client request example to illustrate how the feature works.
```sh
curl -iH "content-type: application/json" http://localhost:8787
# HTTP/1.1 200 OK
# content-type: application/json
# content-length: 163
# cache-control: public, max-age=86400
# date: Tue, 11 Oct 2022 23:24:55 GMT
# [{"name":"spécial directöry","type":"directory","mtime":"2022-10-07T00:53:50Z"},{"name":"index.html.gz","type":"file","mtime":"2022-09-27T22:44:34Z","size":332}]⏎
```
