httpd(3tcl)

📦
version 2.0 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 httpd — Tcl Web Server 💖

okay so bestie, this is the manual page for httpd(3tcl), aka Tcl Web Server. Buckle up, it's a long one, but it's so worth it. 🫶

🌸 NAME 🌸

httpd — a TclOO and coroutine based web server. no cap, it's literally a whole web server living inside Tcl. ✨

🎀 SYNOPSIS 🎀

so first you gotta pull in the whole squad of packages, then you get the methods. here's the full list, exactly as it is:

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

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 🦋

This module implements a web server, and it's built to be embedded right into an application. The server is object oriented, and it comes with all of the fundamentals you need for a full service website. everything. the whole vibe. 👑

🌈 MINIMAL EXAMPLE 🌈

To get a web service going you start 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 them. easy.

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 serve files from a file system. And ooh, files that end in .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. obsessed tbh.

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? — copies a channel, bestie. exactly what it says on the tin.
  • method html_header ?title ? ?args? — Returns a block of HTML. 🎀
  • method html_footer ?args? — the footer half of that. closing tags, closing energy. ✨
  • method http_code_string code — turns an HTTP code into its string form.
  • method HttpHeaders sock ?debug ? — streams the headers out over the socket.
  • method HttpHeaders_Default — the default headers. the base fit. 💖
  • method HttpServerHeaders — the server's own headers.
  • method MimeParse mimetext — Converts a block of mime encoded text to a key/value list. If an exception is encountered, the method will generate its own call to the error method, and immediately invoke the output method to produce an error code and close the connection. so yeah, it handles its own drama. 😭
  • method Url_Decode data — De-httpizes a string.
  • method Url_PathCheck urlsuffix — checks that url suffix, lowkey doing a vibe check on it.
  • method wait mode sock — waits on the socket in the given mode.

🌸 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 whole routine:

  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 a 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 looks like this, and honestly? it's giving range:

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 — the channel registry, keeping track of the channels this object owns. 🎀
  • variable reply — A dictionary which will be 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. like, the parent. the origin story. 💜

Methods

  • method constructor ServerObj ?args? — sets the whole thing up.
  • method destructor ?dictargs? — clean up on exit. gotta leave it tidy bestie. 🧹
  • 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. for the archives. 📝
  • 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. ✨
  • http — a key/value list of values to populate the object's request ensemble. cute.

All the other fields? They get passed along to the clay structure of the object. no notes.

  • Dispatch — the dispatcher. doin its thing.
  • html_header title ?args?
  • html_footer ?args?
  • error code ?msg ? ?errorInfo ?
  • content — REPLACE ME: this method is the literal "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. this is your moment bestie, the main character energy lives here 💅
  • EncodeStatus status — formulates a standard HTTP status header from the string provided.
  • log type ?info ?
  • CoroName
  • DoOutput — generates the HTTP reply, streams that reply back across chan, and then destroys the object. it's giving final act ✨
  • FormData — for GET requests, converts the QUERY_DATA header into a key/value list. For POST requests, reads the Post data and converts that information to 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 back into the mime package to read out the contents. iconic.
  • PostData length — streams length bytes from the chan socket, but only if the request is a POST or PUSH. Returns an empty string otherwise. periodt.
  • Session_Load — manage session data.
  • puts line — appends the value of string to the end of reply_body, plus a trailing newline character.
  • RequestFind field
  • request subcommand ?args?
  • reply subcommand ?args?
  • reset — clears the contents of the reply_body variable, and resets all headers in the reply structure back to the defaults for this object. fresh start fr fr 🧼
  • timeOutCheck — called from the http::server object which spawned this reply. Checks to see if too much time has elapsed while waiting for data or generating a reply, and issues a timeout error to the request if it has, as well as destroying the object and closing the chan socket. ⏰
  • timestamp — returns the current system time in the format:
%a, %d %b %Y %T %Z

🌈 CLASS HTTPD::SERVER 🌈

ancestors: httpd::mime

Variables

  • template
  • url_patterns

Methods

  • constructor args ?port auto? ?myaddr 127.0.0.1? ?string auto? ?name auto? ?doc_root ? ?reverse_dns 0? ?configuration_file ? ?protocol HTTP/1.1?
  • destructor ?dictargs?
  • connect sock ip port — replies to an open socket. This method builds a coroutine to manage the rest of the connection. The coroutine's operations are driven by the Connect method.
  • ServerHeaders ip http_request mimetxt
  • Connect uuid sock ip — this method reads HTTP headers, and then consults the dispatch method to figure out if the request is valid, and/or what kind of reply to generate. Under normal cases, an object of class ::http::reply is created, and that class's dispatch method runs. This action passes control of the socket to the reply object. The reply object manages the rest of the transaction, including closing the socket. 👑
  • counter which — increments an internal counter.
  • CheckTimeout — checks open connections for a time out event.
  • debug ?args?
  • dispatch data — given a key/value list of information, returns a data structure describing how the server should reply.
  • 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 which matches the query.
  • Dispatch_Local data — the dispatch method invoked prior to invoking methods implemented by plugins. If this method returns a non-empty dictionary, that structure will be passed to the reply. The default is an empty implementation.
  • Headers_Local varname — introspect and possibly modify a data structure destined for a reply. This method is invoked before invoking Header methods implemented by plugins. The default implementation is empty.
  • Headers_Process varname — introspect and possibly modify a data structure destined for a reply. This method is built dynamically by the plugin method.
  • HostName ipaddr — convert an ip address to a host name. If the server/reverse_dns flag is false, this method simply returns the IP address back. Internally, this method uses the dns module from tcllib.
  • log ?args? — log an event. The input for args is free form. This method is intended to be replaced by the user, and is a noop for a stock http::server object.
  • plugin slot ?class ? — incorporate behaviors from a plugin. This method dynamically rebuilds the Dispatch and Headers method. For every plugin, the server looks for the following entries in clay plugin/:
    • load — a script to invoke in the server's namespace during the plugin method invokation.
    • 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.
  • port_listening — return the actual port that httpd is listening on. 🎀
  • PrefixNormalize prefix — for the stock version, trim trailing /'s and *'s from a prefix. This method can be replaced by the end user to perform any other transformations needed for the application.
  • source filename
  • start — open the socket listener.
  • stop — shut off the socket listener, and destroy any pending replies.
  • SubObject {} db
  • SubObject {} default
  • template page — return a template for the string page.
  • TemplateSearch page — perform a search 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.
  • Thread_start — built by the plugin method. Called by the start method. Intended to allow plugins to spawn worker threads.
  • Uuid_Generate — generate a GUUID. Used to ensure every request has a unique ID. The default implementation is:
return [::clay::uuid generate]
  • Validate_Connection sock ip — given a socket and an ip address, return 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 for applications to be able to implement black lists and/or provide security based on IP address. 🛡️

🦋 CLASS HTTPD::SERVER::DISPATCH 🦋

ancestors: httpd::server

Provide a backward compadible alias. iykyk.

🌸 CLASS HTTPD::CONTENT.REDIRECT 🌸

Methods

  • reset
  • content

⭐ CLASS HTTPD::CONTENT.CACHE ⭐

Methods

  • Dispatch

🎀 CLASS HTTPD::CONTENT.TEMPLATE 🎀

Methods

  • content

💜 CLASS HTTPD::CONTENT.FILE 💜

Class to deliver Static content. When utilized, this class is fed a local filename by the dispatcher.

Methods

  • FileName
  • DirectoryListing local_file
  • content
  • Dispatch

🔥 CLASS HTTPD::CONTENT.EXEC 🔥

Variable

  • exename

Methods

  • CgiExec execname script arglist
  • Cgi_Executable script

🌈 CLASS HTTPD::CONTENT.PROXY 🌈

ancestors: httpd::content.exec

Return data from an proxy process.

Methods

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

🫶 CLASS HTTPD::CONTENT.CGI 🫶

ancestors: httpd::content.proxy

Methods

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

✨ CLASS HTTPD::PROTOCOL.SCGI ✨

Return data from an SCGI process.

Methods

  • EncodeStatus status

💅 CLASS HTTPD::CONTENT.SCGI 💅

ancestors: httpd::content.proxy

Methods

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

👑 CLASS HTTPD::SERVER.SCGI 👑

ancestors: httpd::server

Act as an SCGI Server.

Methods

  • debug ?args?
  • Connect uuid sock ip

🦋 CLASS HTTPD::CONTENT.WEBSOCKET 🦋

Upgrade a connection to a websocket. lowkey the coolest glow-up a connection can have 💫

🧚 CLASS HTTPD::PLUGIN 🧚

httpd plugin template.

🍓 CLASS HTTPD::PLUGIN.DICT_DISPATCH 🍓

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

Methods

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

💖 CLASS HTTPD::REPLY.MEMCHAN 💖

ancestors: httpd::reply

Methods

  • output
  • DoOutput
  • close

🎀 CLASS HTTPD::PLUGIN.LOCAL_MEMCHAN 🎀

Methods

  • local_memchan command ?args?
  • Connect_Local uuid sock ?args? — a modified connection method that passes simple GET request 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. 😭 fr fr, it's a whole situation.

💖 AUTHORS 💖

Sean Woods

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category network of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](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.

bestie pls don't inline your patch, the maintainers are begging 🙏

⭐ KEYWORDS ⭐

TclOO, WWW, http, httpd, httpserver, services

🌈 CATEGORY 🌈

Networking

okay bestie, final section, and it's the one where we give credit where credit is due, because we are not the kind of girl who forgets to tag people. 🫶

  • Copyright (c) 2018 Sean Woods <yoda@etoyoc.com>

that's it. that's the whole vibe. Sean Woods wrote this thing back in 2018 and honestly? iconic behavior. the email's right there in the backticks if you ever wanna slide into his inbox with a thank-you note (do it, people love that, fr fr 💅).

quick lil reminder bestie:</> a copyright line isn't decoration, it's a real thing. if you're out here copy-pasting this manpage into your own docs, keep the credit attached. stealing credit is not main character energy, it's giving villain arc. 😭

and that's a wrap on httpd(3tcl)! you made it all the way to the bottom, which means you now know more about Tcl HTTP servers than like 90% of the group chat. slay. go build something cute with it. 🦋✨

this page lives in tcllib, version 4.3.6, and the page itself is httpd(3tcl) — no date stamp on this footer, she's simply timeless like that. 👑

bye bestie!! 💖🌸🎀

📦 where this page comes from