httpd(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 httpd(n) — the Tcl Web Server, bestie edition 💖

okay so. say hi to httpd, from the Tcl Web Server manual. this is part 1 of 3, so buckle up buttercup 🎀

✨ SYNOPSIS ✨

first you gotta pull in the whole friend group, fr fr:

package require Tcl 8.6 9
package require uuid
package require clay
package require coroutine
package require fileutil
package require fileutil::magic::filetype
package require websocket
package require mime
package require cron
package require uri
package require Markdown

and here's the full roster of methods and variables, no cap, every single one:

method ChannelCopy in out ?args?
method html_header ?title ? ?args?
method html_footer ?args?
method http_code_string code
method HttpHeaders sock ?debug ?
method HttpHeaders_Default
method HttpServerHeaders
method MimeParse mimetext
method Url_Decode data
method Url_PathCheck urlsuffix
method wait mode sock
variable ChannelRegister
variable reply
variable request
delegate <server>
method constructor ServerObj ?args?
method destructor ?dictargs?
method ChannelRegister ?args?
method close
method Log_Dispatched
method dispatch newsock datastate
method Dispatch
method html_header title ?args?
method html_footer ?args?
method error code ?msg ? ?errorInfo ?
method content
method EncodeStatus status
method log type ?info ?
method CoroName
method DoOutput
method FormData
method PostData length
method Session_Load
method puts line
method RequestFind field
method request subcommand ?args?
method reply subcommand ?args?
method reset
method timeOutCheck
method timestamp
variable template
variable url_patterns
method constructor args ?port auto? ?myaddr 127.0.0.1? ?string auto? ?name auto? ?doc_root ? ?reverse_dns 0? ?configuration_file ? ?protocol HTTP/1.1?
method destructor ?dictargs?
method connect sock ip port
method ServerHeaders ip http_request mimetxt
method Connect uuid sock ip
method counter which
method CheckTimeout
method debug ?args?
method dispatch data
method Dispatch_Default reply
method Dispatch_Local data
method Headers_Local varname
method Headers_Process varname
method HostName ipaddr
method log ?args?
method plugin slot ?class ?
method port_listening
method PrefixNormalize prefix
method source filename
method start
method stop
method SubObject {} db
method SubObject {} default
method template page
method TemplateSearch page
method Thread_start
method Uuid_Generate
method Validate_Connection sock ip
method reset
method content
method Dispatch
method content
method FileName
method DirectoryListing local_file
method content
method Dispatch
variable exename
method CgiExec execname script arglist
method Cgi_Executable script
method proxy_channel
method proxy_path
method ProxyRequest chana chanb
method ProxyReply chana chanb ?args?
method Dispatch
method FileName
method proxy_channel
method ProxyRequest chana chanb
method ProxyReply chana chanb ?args?
method DirectoryListing local_file
method EncodeStatus status
method scgi_info
method proxy_channel
method ProxyRequest chana chanb
method ProxyReply chana chanb ?args?
method debug ?args?
method Connect uuid sock ip
method Dispatch_Dict data
method uri {} add vhosts patterns info
method uri {} direct vhosts patterns info body
method output
method DoOutput
method close
method local_memchan command ?args?
method Connect_Local uuid sock ?args?

🌸 DESCRIPTION 🌸

okay so this module is a whole web server, and the whole point is that you can embed it inside your app 🫶. it's object oriented, and it's got literally all the fundamentals you need for a full service website. it's giving "I contain multitudes" energy 💅

🦋 MINIMAL EXAMPLE 🦋

to spin up a web service you gotta create a class of type httpd::server, hand that server one or more URIs to service, and give it httpd::reply derived classes to actually generate those URIs. the vibes:

oo::class create ::reply.hello {
  method content {} {
    my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
    my puts "<h1>Hello World!</h1>"
    my puts </BODY></HTML>
  }
}
::httpd::server create HTTPD port 8015 myaddr 127.0.0.1 doc_root ~/htdocs
HTTPD plugin dispatch httpd::server::dispatch
HTTPD uri add * /hello [list mixin reply.hello]

the bare module does have facilities to hose a files from a file system, bestie. files that end in a .tml get substituted in the style of Tclhttpd:

<!-- hello.tml -->
[my html_header {Hello World!}]
Your Server is running.
<p>
The time is now [clock format [clock seconds]]
[my html_footer]

there's a complete example of an httpd server in the /examples directory of Tcllib 👑. it also shows how to dispatch URIs to other processes via SCGI and HTTP proxies, which is lowkey iconic:

cd ~/tcl/sandbox/tcllib
tclsh examples/httpd.tcl

👑 CLASSES 👑

💜 CLASS HTTPD::MIME

a metaclass for MIME handling behavior across a live socket ✨

Methods

  • method ChannelCopy in out ?args?
  • method html_header ?title ? ?args? — returns a block of HTML 📄
  • method html_footer ?args?
  • method http_code_string code
  • method HttpHeaders sock ?debug ?
  • method HttpHeaders_Default
  • method HttpServerHeaders
  • method MimeParse mimetext — converts a block of mime encoded text to a key/value list. but listen: if an exception gets encountered, the method generates its own call to the error method, and immediately invokes the output method to produce an error code and close the connection. so it handles its own drama 💀
  • method Url_Decode data — de-httpizes a string 🧚
  • method Url_PathCheck urlsuffix
  • method wait mode sock

🎀 CLASS HTTPD::REPLY

ancestors: httpd::mime

a class which shephards a request through the process of generating a reply 🫶. the socket associated with the reply is available at all times as the chan variable. the process of generating a reply begins with an httpd::server generating a http::class object, mixing in a set of behaviors and then invoking the reply object's dispatch method. in normal operations the dispatch method does this, in order:

  1. invokes the reset method for the object to populate default headers ✨
  2. invokes the HttpHeaders method to stream the MIME headers out of the socket 💌
  3. invokes the request parse method to convert the stream of MIME headers into a dict that can be read via the request method 📖
  4. stores the raw stream of MIME headers in the rawrequest variable of the object 🗂️
  5. invokes the content method for the object, generating an call to the error method if an exception is raised 😭
  6. invokes the output method for the object 🚀

developers have the option of streaming output to a buffer via the puts method of the reply, or simply populating the reply_body variable of the object. the information returned by the content method is not interpreted in any way 🙈. if an exception is thrown (via the error command in Tcl, for example) the caller will auto-generate a 500 {Internal Error} message 💀. a typical implementation of content look like:

clay::define ::test::content.file {
  superclass ::httpd::content.file
  # Return a file
  # Note: this is using the content.file mixin which looks for the reply_file variable
  # and will auto-compute the Content-Type
  method content {} {
    my reset
    set doc_root [my request get DOCUMENT_ROOT]
    my variable reply_file
    set reply_file [file join $doc_root index.html]
  }
}
clay::define ::test::content.time {
  # return the current system time
  method content {} {
     my variable reply_body
    my reply set Content-Type text/plain
     set reply_body [clock seconds]
  }
}
clay::define ::test::content.echo {
  method content {} {
     my variable reply_body
    my reply set Content-Type [my request get CONTENT_TYPE]
     set reply_body [my PostData [my request get CONTENT_LENGTH]]
  }
}
clay::define ::test::content.form_handler {
  method content {} {
    set form [my FormData]
    my reply set Content-Type {text/html; charset=UTF-8}
    my puts [my html_header {My Dynamic Page}]
    my puts "<BODY>"
    my puts "You Sent<p>"
    my puts "<TABLE>"
    foreach {f v} $form {
      my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
    }
    my puts "</TABLE><p>"
    my puts "Send some info:<p>"
    my puts "<FORM action=/[my request get REQUEST_PATH] method POST>"
    my puts "<TABLE>"
    foreach field {name rank serial_number} {
      set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
      if {[dict exists $form $field]} {
        append line " value=\"[dict get $form $field]\"""
      }
      append line " /></TD></TR>"
      my puts $line
    }
    my puts "</TABLE>"
    my puts [my html footer]
  }
}

Variable

  • variable ChannelRegister
  • variable reply — a dictionary which will converted into the MIME headers of the reply 💌
  • variable request — a dictionary containing the SCGI transformed HTTP headers for the request 📬

Delegate

  • delegate <server> — the server object which spawned this reply 👑

Methods

  • method constructor ServerObj ?args?
  • method destructor ?dictargs? — clean up on exit 🧹
  • method ChannelRegister ?args? — registers a channel to be closed by the close method
  • method close — close channels opened by this object 🚪
  • method Log_Dispatched — record a dispatch event 📝
  • method dispatch newsock datastate — accept the handoff from the server object of the socket newsock and feed it the state datastate. fields the datastate are looking for in particular are:
    • mixin — a key/value list of slots and classes to be mixed into the object prior to invoking Dispatch.

(part 2 is coming bestie, don't go anywhere 💖)

  • http — a key/value list of values that populates the object's request ensemble ✨

All the other fields get passed along to the clay structure of the object. that's the whole note 💅

  • method Dispatch — the source gives us literally zero description here, so... mystery 💀
  • method html_header title ?args? — no notes in the original, bestie 🎀
  • method html_footer ?args? — also undescribed, we move 🦋
  • method error code ?msg ? ?errorInfo ? — no description given 🙈
  • method content — REPLACE ME: this method is the "meat" of your application 🔥 It writes to the result buffer via the puts method, and it can tweak the headers via clay put header_reply.
  • method EncodeStatus status — formulates a standard HTTP status header from the string provided 🎀
  • method log type ?info ? — no description in the source, iykyk
  • method CoroName — undescribed 🦋
  • method DoOutput — generates the HTTP reply, streams that reply back across chan, and destroys the object 💥
  • method FormData — okay so for GET requests this converts the QUERY_DATA header into a key/value list. For POST requests, it reads the Post data and converts that info into a key/value list for application/x-www-form-urlencoded posts. For multipart posts, it composites all of the MIME headers of the post into a singular key/value list, and provides MIME_* information as computed by the mime package — including the MIME_TOKEN, which can be fed right back into the mime package to read out the contents 👑
  • method PostData length — streams length bytes from the chan socket, but only if the request is a POST or PUSH. Returns an empty string otherwise ✨
  • method Session_Load — manages session data 🌸
  • method puts line — appends the value of string to the end of reply_body, plus a trailing newline character 🫶
  • method RequestFind field — no description given 💜
  • method request subcommand ?args? — undescribed, moving on ✨
  • method reply subcommand ?args? — same, no notes 🎀
  • method reset — clears the contents of the reply_body variable, and resets all the headers in the reply structure back to the defaults for this object 🧚
  • method timeOutCheck — called from the http::server object that spawned this reply. It checks whether too much time has elapsed while waiting for data or generating a reply, and if it has, it issues a timeout error to the request, destroys the object, and closes the chan socket 💀
  • method timestamp — returns the current system time in this format:
%a, %d %b %Y %T %Z

🎀 CLASS HTTPD::SERVER 🎀

ancestors: httpd::mime

🍓 Variable

  • variable template
  • variable url_patterns

✨ Methods ✨

  • method constructor args ?port auto? ?myaddr 127.0.0.1? ?string auto? ?name auto? ?doc_root ? ?reverse_dns 0? ?configuration_file ? ?protocol HTTP/1.1? — no description in the source, but look at all those defaults, bestie 👑
  • method destructor ?dictargs? — undescribed 💀
  • method connect sock ip port — replies to an open socket. This method builds a coroutine to manage the rest of the connection, and that coroutine's operations are driven by the Connect method 🦋
  • method ServerHeaders ip http_request mimetxt — no description given 🎀
  • method Connect uuid sock ip — this one reads the HTTP headers, then consults the dispatch method to figure out whether the request is valid and/or what kind of reply to generate. In the normal case, an object of class ::http::reply gets created, and that class's dispatch method runs. This hands control of the socket over to the reply object, and the reply object manages the rest of the transaction — including closing the socket 💅
  • method counter which — increments an internal counter ✨
  • method CheckTimeout — checks open connections for a time out event 💜
  • method debug ?args? — undescribed 🙈
  • method dispatch data — given a key/value list of information, returns a data structure describing how the server should reply 👑
  • method Dispatch_Default reply — the dispatch method of last resort, before returning a 404 NOT FOUND error. The default behavior is to look for a file in DOCUMENT_ROOT that matches the query 🔥
  • method Dispatch_Local data — the dispatch method invoked before any methods implemented by plugins run. If this method returns a non-empty dictionary, that structure gets passed to the reply. The default is an empty implementation 🌸
  • method Headers_Local varname — introspects and possibly modifies a data structure destined for a reply. Invoked before the Header methods implemented by plugins run. The default implementation is empty 🦋
  • method Headers_Process varname — introspects and possibly modifies a data structure destined for a reply. This method is built dynamically by the plugin method ✨
  • method HostName ipaddr — converts an ip address into a host name. If the server's reverse_dns flag is false, this method just hands the IP address right back. Internally it uses the dns module from tcllib 💖
  • method log ?args? — logs an event. The input for args is free form. This method is intended to be replaced by the user, and it's a noop for a stock http::server object 🎀
  • method plugin slot ?class ? — incorporates behaviors from a plugin. This method dynamically rebuilds the Dispatch and Headers methods. For every plugin, the server looks for these entries in clay plugin/:
    • load — a script to invoke in the server's namespace during the plugin method invocation.
    • dispatch — a script to stitch into the server's Dispatch method.
    • headers — a script to stitch into the server's Headers method.
    • thread — a script to stitch into the server's Thread_start method.
  • method port_listening — returns the actual port that httpd is listening on 🌈
  • method PrefixNormalize prefix — for the stock version, trims trailing /'s and *'s from a prefix. The end user can replace this method to perform any other transformations their application needs 🧚
  • method source filename — undescribed 💀
  • method start — opens the socket listener 🔥
  • method stop — shuts off the socket listener, and destroys any pending replies 💅
  • method SubObject {} db — no description given 🎀
  • method SubObject {} default — also undescribed 🦋
  • method template page — returns a template for the string page ✨
  • method TemplateSearch page — searches for the template that best matches page. This can include local file searches, in-memory structures, or even database lookups. The stock implementation simply looks for files with a .tml or .html extension in the ?doc_root? directory 🌸
  • method Thread_start — built by the plugin method. Called by the start method. Intended to let plugins spawn worker threads 👑
  • method Uuid_Generate — generates a GUUID. Used to make sure every request has a unique ID. The default implementation is:
return [::clay::uuid generate]
  • method Validate_Connection sock ip — given a socket and an ip address, returns true if this connection should be terminated, or false if it should be allowed to continue. The stock implementation always returns 0. This is intended so applications can implement black lists and/or provide security based on IP address 💖

🎀 CLASS HTTPD::SERVER::DISPATCH 🎀

ancestors: httpd::server

Provides a backward compatible alias ✨

🎀 CLASS HTTPD::CONTENT.REDIRECT 🎀

✨ Methods ✨

  • method reset
  • method content

🎀 CLASS HTTPD::CONTENT.CACHE 🎀

✨ Methods ✨

  • method Dispatch

🎀 CLASS HTTPD::CONTENT.TEMPLATE 🎀

✨ Methods ✨

  • method content

🎀 CLASS HTTPD::CONTENT.FILE 🎀

A class to deliver static content. When it's utilized, this class gets fed a local filename by the dispatcher 🍓

✨ Methods ✨

  • method FileName
  • method DirectoryListing local_file
  • method content
  • method Dispatch

🎀 CLASS HTTPD::CONTENT.EXEC 🎀

🍓 Variable

  • variable exename

✨ Methods ✨

  • method CgiExec execname script arglist
  • method Cgi_Executable script

🎀 CLASS HTTPD::CONTENT.PROXY 🎀

ancestors: httpd::content.exec

Returns data from a proxy process 🦋

✨ Methods ✨

  • method proxy_channel
  • method proxy_path
  • method ProxyRequest chana chanb
  • method ProxyReply chana chanb ?args?
  • method Dispatch

🎀 CLASS HTTPD::CONTENT.CGI 🎀

ancestors: httpd::content.proxy

✨ Methods ✨

  • method FileName
  • method proxy_channel
  • method ProxyRequest chana chanb
  • method ProxyReply chana chanb ?args?
  • method DirectoryListing local_file — for most CGI applications a directory list is vorboten 💀

🎀 CLASS HTTPD::PROTOCOL.SCGI 🎀

Returns data from an SCGI process 🎀

✨ Methods ✨

  • method EncodeStatus status

🎀 CLASS HTTPD::CONTENT.SCGI 🎀

ancestors: httpd::content.proxy

✨ Methods ✨

  • method scgi_info
  • method proxy_channel
  • method ProxyRequest chana chanb
  • method ProxyReply chana chanb ?args?

🎀 CLASS HTTPD::SERVER.SCGI 🎀

ancestors: httpd::server

Acts as an SCGI Server 👑

✨ Methods ✨

  • method debug ?args?
  • method Connect uuid sock ip

🎀 CLASS HTTPD::CONTENT.WEBSOCKET 🎀

Upgrades a connection to a websocket 🌈

🎀 CLASS HTTPD::PLUGIN 🎀

httpd plugin template 🎀

🎀 CLASS HTTPD::PLUGIN.DICT_DISPATCH 🎀

A rudimentary plugin that dispatches URLs from a dict data structure 🍓

✨ Methods ✨

  • method Dispatch_Dict data — implementation of the dispatcher 💅
  • method uri {} add vhosts patterns info
  • method uri {} direct vhosts patterns info body

🎀 CLASS HTTPD::REPLY.MEMCHAN 🎀

ancestors: httpd::reply

✨ Methods ✨

  • method output
  • method DoOutput
  • method close

🎀 CLASS HTTPD::PLUGIN.LOCAL_MEMCHAN 🎀

✨ Methods ✨

  • method local_memchan command ?args?
  • method Connect_Local uuid sock ?args? — a modified connection method that passes simple GET requests to an object and pulls data directly from the reply_body data variable in the object. Needed because memchan is bidirectional, and we can't seem to communicate that the server is one side of the link and the reply is another 💀

👑 AUTHORS 👑

Sean Woods

💖 BUGS, IDEAS, FEEDBACK 💖

This document, and the package it describes, will undoubtedly contain bugs and other problems. bestie, please report such in the category network of the Tcllib Trackers http://core.tcl.tk/tcllib/reportlist 🫶 Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar 💅

✨ KEYWORDS ✨

TclOO, WWW, http, httpd, httpserver, services

🌈 CATEGORY 🌈

Networking

Okay bestie, legal era, we're almost done, stay with me 🫶

Copyright © 2018 Sean Woods <yoda@etoyoc.com> — that's the icon who made this whole thing, show some respect 💅✨

And that's a wrap on the whole page, fr fr 🎀 — brought to you by tcllib, version 4.3.6, starring our main character httpd(n). Go forth and serve some pages, you absolute legend 👑🌸

📦 where this page comes from