GOLF(2gg)

📦 version 601.4.41, in ubuntu questing

💖 GOLF(2gg) 💖 — like, the out-header page, bestie

okay so this is from the GOLF(2gg) manual (Development section, iykyk) and we're talking about out-header and honestly? it's giving "quietly essential" ✨

🌸 NAME 🌸

out-header — (web) 🦋

🎀 PURPOSE 🎀

Output HTTP header. that's it. that's the whole job. 👑

✨ SYNTAX ✨

out-header default
|
out-header use \
    [ content-type <content type> ] \
    [ download [ <download> ] ] \
    [ etag [ <etag> ] ] \
    [ file-name <file name> ] \
    [ ( cache-control <cache control> ) | no-cache ] \
    [ status-id <status id> ] \
    [ status-text <status text> ] \
    [ custom <header name>=<header value> [ , ... ] ]

💅 DESCRIPTION 💅

so out-header outputs the HTTP header, and it also sends any cookies produced by set-cookie and delete-cookie. 🍪✨ a web page must have an HTTP header output before any other response. like, non-negotiable. the vibes demand it.

If out-header is not used, a default HTTP header is sent out just before the very first output (see output-statement, print-out etc.) — and at that point any cookie updates are sent as well. this default header is the same as using out-header default. 🫶

If you use out-header multiple times, all but the very first one are ignored. the rest are just there, standing in the corner, not participating. 💀

If you wish to output a file (such as an image or a PDF document), do not use out-header; rather use send-file instead, which outputs its own header. don't be messy about it, bestie. 🙈

The HTTP header is sent back to a client who initiated a request. You can specify any custom headers with the use clause. 🌈

👑 DEFAULT HEADER 👑

If no out-header is used, or if the default clause is in place, a default header is constructed, which uses a status of 200/OK and content type of

text/html;charset=utf-8

and cache control of

Cache-Control:max-age=0, no-cache; Pragma: no-cache

The default header is typical for dynamically generated web pages, and most of the time you would use the default header — meaning you don't need to specify out-header statement at all. lowkey the easiest win ever. 🍓

🦋 HEADERS 🦋

The following are subclauses that allow setting any custom header:

  • <content type> is content type (such as "text/html" or "image/jpg" etc.) If you are sending a file to a client for download and you don't know its content type, you can use "application/octet-stream" for a generic binary file.
  • If download is used without boolean variable <download>, or if <download> evaluates to true, then the file is sent to a client for downloading — otherwise the default is to display file in client.
  • <file name> is the name of the file being sent to a client. This is not the local file name — it is the file name that client will use for its own purposes. (the client's business, not yours 💅)
  • <cache control> is the cache control HTTP header. "no-cache" instructs the client not to cache. Only one of cache-control and no-cache can be used. An example of <cache control>:
send-file "somepic.jpg" headers cache-control "max-age: 3600"
  • If etag is used without boolean variable <etag>, or if <etag> evaluates to true, then "ETAG" header will be generated (a timestamp) and included, otherwise it is not. The time stamp is of last modification date of the file (and typically used to cache a file on client if it hasn't changed on the server). etag is useful to let the client know to download the file only once if it hasn't changed, thus saving network and computing resources. ETAG header is used only for send-file.
  • <status id> and <status text> are status settings for the response, as strings (such as "425" for status-id and "Too early" for status-text).
  • To set any type of generic HTTP header, use custom subclause, where <header name> and <header value> represent the name and value of a single header. Multiple headers are separated by a comma. There is no limit on the maximum number of such headers, other than of the underyling HTTP protocol. You must not use custom to set headers already set elsewhere (such as etag for instance), as that may cause unpredictable behavior. For instance this sets two custom headers:
out-header use custom "CustomOption3"="CustomValue3", "Status"="418 I'm a teapot"

custom subclause lets you use any custom headers that exist today or may be added in the future, as well as any headers of your own design. the future is yours, main character energy fr fr. 🔥

⚠️ bestie, careful: no setting headers with custom that are already set elsewhere. unpredictable behavior is NOT the vibe check we're going for. 😭

You can use silent-header before output-header in order to suppress its output. 🤫

🌟 EXAMPLES 🌟

Sometimes you may want to output the default header immediately, for instance if the first output produces may take some time:

out-header default

To set a custom header for a web page that changes cache control and adds two new headers:

out-header use content-type "text/html" cache-control "max-age:3600" custom "some_HTTP_option"="value_for_some_HTTP_option", "some_HTTP_option_1"="value_for_some_HTTP_option_1"

💜 SEE ALSO 💜

  • Web
  • call-web, out-header, send-file, silent-header, See all documentation

and that's the whole page bestie, ate and left no crumbs 🎀✨

This one's from the GOLF $VERSION build, dated $DATE — mwah, go slay your HTTP headers 💅🦋💖

📦 where this page comes from