hs.httpserver
, this module adds support for serving static pages stored at a specified document root as well as serving dynamic content from Lua Template Files interpreted within the Hammerspoon environment and external executables which support the CGI/1.1 framework.hs.httpserver
, Hammerspoon's web serving capabilities will never replace a dedicated web server when volume or speed is required.hsdocs
folder of the hs.doc
module. This web site can serve documentation for Hammerspoon dynamically generated from the json file included with the Hammerspoon application for internal documentation. It serves as a basic example of what is possible with this module.require("hs.doc.hsdocs").start()
and then visiting http://localhost:12345/
with your web browser.hs.httpserver.hsminweb.dateFormatString
os.date
, which will display a date in the format expected for HTTP communications as described in RFC 822, updated by RFC 1123.hs.httpserver.hsminweb.statusCodes
hs.httpserver.hsminweb.statusCodes
hs.httpserver.hsminweb._accessLog
self._accessLog
. If query logging is enabled for the web server, an Apache style common log entry will be appended to this string for each request. See hs.httpserver.hsminweb:queryLogging.hs.httpserver.hsminweb._errorHandlers
self._errorHandlers[errorCode]
. A table whose keyed entries specify the function to generate the error response page for an HTTP error.hs.httpserver.hsminweb._serverAdmin
self._serverAdmin
. A string containing the administrator for the web server. Defaults to the currently logged in user's short form username and the computer's localized name as returned by hs.host.localizedName()
(e.g. "[email protected]").hs.httpserver.hsminweb._supportMethods
self._supportMethods[method]
. A table whose keyed entries specify whether or not a specified HTTP method is supported by this server.hs.httpserver.hsminweb.log
hs.logger
instance for the hs.httpserver.hsminweb
module. See the documentation for hs.logger
for more information.hs.httpserver.hsminweb.formattedDate([date]) -> string
os.time()
hs.httpserver.hsminweb.urlParts(url) -> table
hs.http.urlParts
in a few ways:hs.http.urlParts
uses OS X API functions which are patterned after RFC 1808. RFC 3986 obsoletes 1808. The primary distinction that affects this module is in regards to parameters
for path components in the URI -- RFC 3986 disallows them in schema based URI's (like the URL's that are used for web based traffic).hs.httpserver.hsminweb.new([documentRoot]) -> hsminwebTable
Sites
sub-directory (i.e. os.getenv("HOME").."/Sites"
).hs.httpserver.hsminweb:accessList([table]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the access-list table for the hsminweb web server | | Parameters |nil
containing the access list for the web server, default nil
.nil
), then all requests are served. If a table is passed into this method, then any request which is not explicitly accepted by one of the tests provided is rejected (i.e. there is an implicit "reject" at the end of the list).value
as a pattern match (true) -- see Lua documentation 6.4.1, help.lua._man._6_4_1
in the console, or as an exact match (false)hs.httpserver.hsminweb:allowDirectory([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not a directory index is returned when the requested URL specifies a directory and no file matching an entry in the directory indexes table is found. | | Parameters |hs.httpserver.hsminweb:bonjour([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not the web server should advertise itself via Bonjour when it is running. | | Parameters |hs.httpserver.hsminweb:cgiEnabled([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not CGI file execution is enabled. | | Parameters |hs.httpserver.hsminweb:cgiExtensions([table]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the file extensions which identify files which should be executed as CGI scripts to provide the results to an HTTP request. | | Parameters |nil
, defaults to { "cgi", "pl" }
, specifying a list of file extensions which indicate that a file should be executed as CGI scripts to provide the content for an HTTP request.hs.httpserver.hsminweb:directoryIndex([table]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the file names to look for when the requested URL specifies a directory. | | Parameters |nil
, defaults to { "index.html", "index.htm" }
, specifying a list of file names to look for when the requested URL specifies a directory. If a file with one of the names is found in the directory, this file is served instead of the directory.hs.httpserver.hsminweb:dnsLookup([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not DNS lookups are performed. | | Parameters |hs.httpserver.hsminweb:documentRoot([path]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the document root for the web server. | | Parameters |os.getenv("HOME") .. "/Sites"
, specifying where documents for the web server should be served from.hs.httpserver.hsminweb:interface([interface]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the network interface that the hsminweb web server will listen on | | Parameters |hs.httpserver.setInterface
for a description of valid values that can be specified as the interface
argument to this method.hs.httpserver.hsminweb:luaTemplateExtension([string]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the extension of files which contain Lua code which should be executed within Hammerspoon to provide the results to an HTTP request. | | Parameters |nil
, defaults to nil
, specifying the file extension which indicates that a file should be executed as Lua code within the Hammerspoon environment to provide the content for an HTTP request.hs.httpserver.hsminweb:maxBodySize([size]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the maximum body size for an HTTP request | | Parameters |hs.httpserver
will respond with a status code of 405 for the method before this module ever receives the request.hs.httpserver.hsminweb:name([name]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the name the web server uses in Bonjour advertisement when the web server is running. | | Parameters |nil
, which causes the server to be advertised with the computer's name as defined in the Sharing preferences panel for the computer.hs.httpserver.hsminweb:password([password]) -> hsminwebTable | boolean
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Set a password for the hsminweb web server, or return a boolean indicating whether or not a password is currently set for the web server. | | Parameters |nil
to remove an existing password.hs.httpserver
, so it has the same limitations regarding server passwords. See the documentation for hs.httpserver.setPassword
(help.hs.httpserver.setPassword
in the Hammerspoon console).hs.httpserver.hsminweb:port([port]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the name the port the web server listens on | | Parameters |nil
, which causes the server to randomly choose a port when it is started.hs.httpserver.hsminweb:queryLogging([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not requests to this web server are logged. | | Parameters |hs.logger
instance saved to hs.httpserver.hsminweb.log.hs.httpserver.hsminweb:scriptTimeout([integer]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the timeout for a CGI script | | Parameters |hs.httpserver
, any script which is expected to return content for an HTTP request must run in a blocking manner -- this means that no other Hammerspoon activity can be occurring while the script is executing. This parameter lets you set the maximum amount of time such a script can hold things up before being terminated.hs.httpserver
is being considered which may make it possible to use hs.task
for these scripts, which would alleviate this blocking behavior. However, even if this is addressed, a timeout for scripts is still desirable so that a client making a request doesn't sit around waiting forever if a script is malformed.hs.httpserver.hsminweb:ssl([flag]) -> hsminwebTable | current-value
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the whether or not the web server utilizes SSL for HTTP request and response communications. | | Parameters |hs.httpserver
, so it has the same considerations regarding SSL. See the documentation for hs.httpserver.new
(help.hs.httpserver.new
in the Hammerspoon console).hs.httpserver.hsminweb:start() -> hsminwebTable
hs.httpserver.hsminweb:stop() -> hsminwebTable