File Serving¶

To serve files with pluginserver the fileserve.py plugin must be used. This plugin accepts requests for files, and serves their content to the requesting client.

Files and Content¶

When a file is requested, the mime type of the file is determined using the Python mimetypes pacage so the correct content type headers before sending the content to the client. In the event the mime type cannot be determined the default of 'application/octet-stream' is used.

Markdown¶

Markdown ia an incredibly simple and useful way to express data. This plugin automatically converts markdown to html. The first top-level heading in the markdown file is used for the page title. This is inserted into the html template before serving the file.

Markdown Styling¶

Markdown styling is done by default with markdown.css and highlight.css (the latter for syntax hightlighting). The highlighting CSS I used in testing was generated with Pygments. To generate a highlight_css using Pygments you can run the command:

pygmentize -S <style> -f html > highlight.css # use pygmentize -L styles for list

Magic Variables¶

The file server plugin parses output (html or markdown) for ‘magic’ variables. These are:

Variable	Usage
`@TITLE=Document Title@`	Set the markdown document title
`@INCLUDE=[<path>/]file@`	Include the contents of file
`@TIME=+format@`	Include the time of day with optionl format
`@FILETIME=filepath+format@`	Include the modification time of filepath with optional +format

For include, absolute paths may be used, and, are converted for user path with tilde expansion. Relative paths are made relative to the directory the markdown is served from. Included data is not parsed, it is included verbatim.

For formatting dates the format should be a plus sign (+) followd by one or more of the following:

Code	Meaning
%a	Locale’s abbreviated weekday name
%A	Locale’s full weekday name
%b	Locale’s abbreviated month name
%B	Locale’s full month name
%c	Locale’s appropriate date and time representation
%d	Day of the month as a decimal number [01,31]
%f	Microseconds as a decimal number
%I	Hour (12-hour clock) as a decimal number [01,12]
%j	Day of the year as a decimal number [001,366]
%m	Month as a decimal number [01,12]
%M	Minute as a decimal number [00,59]
%p	Locale’s equivalent of either AM or PM
%S	Second as a decimal number [00,61]
%U	Week number of the year (Sunday as the first day of the week) as a decimal number
%u	Day of the week (Monday is 1; Sunday is 7) as a decimal number [1, 7]
%w	Weekday as a decimal number [0(Sunday),6]
%W	Week number of the year (Monday as the first day of the week) as a decimal number
%x	Locale’s appropriate date representation
%X	Locale’s appropriate time representation
%y	Year without century as a decimal number [00,99]
%Y	Year with century as a decimal number
%z	Time zone offset indicating a positive or negative time difference from UTC/GMT
%Z	Time zone name (no characters if no time zone exists).
%V	ISO 8601 week number (as a decimal number [01,53]).
%%	A literal ‘%’ character

Any other characters between @’s including spaces are replaced verbatim.

A magic variable of @TIME+%A %B $d, %Y@ would yield a string like “Monday May 5, 2025”

Markdown Configuration¶

To set the names for the css used, the following config parameters are used. These files should be path relative to the request path, so, for example, [proto]://server.domain.tld:port/docs/markdown.css would need to be located in the documents path specified in the configuration. Please see Plugin Configuration for the detailed configuration settings.

Path Resuolution¶

The fileserve plugin is configured for a base path, or, document root using configuration paramaters, discussed below in the Plugin Configuration below.

When a path is requested, it is first checked to see if it is a directory or file. If it is a file and the file is readable, its content is sent to the client.

If the file is a directory, configured index file is appended to the directory and service is attempted. When exceptions occur trying to serve the file appropriate errors are returned to the client as both status codes and error text.

Error Handling¶

When Python exceptions are encountered, they are translated to HTTP status codes and error messages.

Plugin Configuraiton¶

The file server plugin, fileserve.py, uses some config values to set itself up. WHen availabe and configured the file server plugin serves files out of a configured directory.

To configure this plugin, the configuration can be modified as below. In order for this configurtion work the fileserve.py plugin must me present in the config.paths.plugins path.

[file_server]
# These options control fileservice if fileserer.py is used.
# Keys are
# common_log: This sets the file name for the access log in CLF
# markdown_css: This is the CSS used for markdown, default is markdown_css
# highlight_css: This is the CSS used to highlight code in markdwon
# indexfile: This is the name of he file used when a directory path is used.
# documents: This is used to set the document root for fileservice
# log_includes: If common_log is set, files included with magic vars are logged
# markdown_envelope: if set is the file used to wrap rendered markdow.
#   The format of this is:
#        documents=html:/path/to/documents
#                        ^-- Path to documents
#                   ^-- This is the root request path if not supplied, docs is used
#  The default is: documents=docs
#
# Any path containing a tilde (~) is resolved to a home directory. 
#
common_log=/path/to/logs/access_log
markdown_css=markdown.css
highlight_css=highlight.css
documents=html:/path/to/docs
indexfile=app.html
log_includes=bool:false
markdown_envelope=/path/to/file.html

A note about CLF. CLF is part of the LogJam logging module, howwever the LogJam.common_log function writes to the CLF format log independently.

Documents Path¶

The documents path may have two parts, but, one is required. The parts are separated by a colon (:). The path component before the colon is used to ‘name’ the request path. If this part is not defined, the basename of the path supplied is used as the request path. These variables are evaluated as below:

Path	Request Path	Documents Directory
`documents=html:${ENV:HOME}}/apidocs`	html	/home/user/apidocs
`documents=/usr/share/apidocs`	apidocs	/usr/share/apidocs
`documents=apidocs`	apidocs	`<cwd>`/apidocs

Index File¶

The optional indexfile=app.html key sets the default name of the file to be served when a document is not specified. If this is not set, index.html is used.

When a document is requested, but, the path is a directory, the indexfie will be appended to that directory and service is attempted.

When file service is requested but the access to the file is denied, i.e., it doesn’t exist, access is denied by the OS or some other exception is encountered, appropriate HTTP status is sent along with an error message.

When file service is complete without errors, a status of 200 and the contents of the file are sent to the client.