From 3d8c74b99d3b0ba4be340b08841f39ee59f611f6 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Wed, 12 Oct 2022 21:55:11 +0200 Subject: [PATCH] docs: directory listing format [skip ci] refs #151 --- 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(-) diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index d1f40a7..6890a33 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -39,11 +39,11 @@ OPTIONS: Server TOML configuration file path [env: SERVER_CONFIG_FILE=] -j, --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 - 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 Specify an optional CORS list of exposed headers separated by commas. Default "origin, content-type". It @@ -52,6 +52,9 @@ OPTIONS: -z, --directory-listing Enable directory listing for all requests ending with the slash character (‘/’) [env: SERVER_DIRECTORY_LISTING=] [default: false] + --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 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 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 Host port [env: SERVER_PORT=] [default: 80] + -p, --port Host port [env: SERVER_PORT=] [default: 80] --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] diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md index c920cde..cd819ab 100644 --- a/docs/content/configuration/config-file.md +++ b/docs/content/configuration/config-file.md @@ -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 diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index 58895b4..1fd2baa 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -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). diff --git a/docs/content/features/directory-listing.md b/docs/content/features/directory-listing.md index 9c174c7..ffe116d 100644 --- a/docs/content/features/directory-listing.md +++ b/docs/content/features/directory-listing.md @@ -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}]⏎ +``` -- libgit2 1.7.2