GOLF(2gg)

📦 version 601.4.41, in ubuntu questing

💖 NAME 💖

send-file — the (web) glow-up where you send a file to your client 🫶

🎯 PURPOSE 🎯

Send a file to the client. That's it, that's the whole vibe. 👑

✨ SYNTAX ✨

send-file <file> [ headers \
    [ 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 when a client is like "hey bestie, I want this file", you hit send-file and hand over <file> — that's its location on the server. It can be a full path OR relative to the application home directory (peep directories for that one 👀).

But listen. You can NEVER use dot-dot (i.e. "..") in <file> — that's a security measure, no cap, it exists specifically to avoid path-traversal attacks. So the file name should literally never have ".." in it, and if it does? The program will error out. Periodt. 🚫

🎀 HEADERS 🎀

These are the subclauses that let you set any custom header you want:

  • <content type> — the content type, bestie. Like "text/html" or "image/jpg" etc. And if you're sending a file to a client for download and you genuinely have no idea what its content type is, just use "application/octet-stream" for a generic binary file. Slay, mystery file. 💅
  • download — if "download" is used without the boolean variable <download>, OR if <download> evaluates to true, then the file gets sent to the client for downloading. Otherwise? The default is to display the file in the client. Choose your fighter. ✨
  • <file name> — this is the name of the file being sent to a client. ⚠️ NOT the local file name, okay? It's the file name that the client will use for its own purposes. Don't get it twisted.
  • <cache control> — this is the cache control HTTP header. "no-cache" instructs the client not to cache. And listen: only ONE of "cache-control" and "no-cache" can be used. Pick a lane. Here's an example of <cache control>:
send-file "somepic.jpg" headers cache-control "max-age: 3600"
  • etag — if "etag" is used without the boolean variable <etag>, OR if <etag> evaluates to true, then an "ETAG" header will be generated (a timestamp) and included. Otherwise it's not included. That timestamp is the last modification date of the file, and it's typically used to cache a file on the client if it hasn't changed on the server. "etag" is genuinely useful — it lets the client know to download the file only once if it hasn't changed, which saves network and computing resources. Obsessed. 🔥 Oh and heads up: the ETAG header is used only for send-file.
  • <status id> and <status text> — these are status settings for the response, as strings. Like "425" for "status-id" and "Too early" for "status-text". Simple as.
  • custom — to set ANY type of generic HTTP header, use the "custom" subclause, where <header name> and <header value> represent the name and value of a single header. Multiple headers get separated by a comma. And ngl, there's no limit on the maximum number of such headers, other than the limits of the underlying HTTP protocol itself. 🌈
🚨 Real talk: you must NOT use "custom" to set headers that are already set elsewhere (like "etag" for instance), because that may cause unpredictable behavior. Don't do it, bestie.

For instance, this sets two custom headers:

out-header use custom "CustomOption3"="CustomValue3", "Status"="418 I'm a teapot"

The "custom" subclause lets you use any custom headers that exist today OR may be added in the future, plus any headers of your own design. Main character energy for your headers, fr fr. 👑

🍓 COOKIES 🍓

Any cookies set prior to send-file (see set-cookie and delete-cookie) will be sent along with the file to the web client. They're coming with us. 🫶

🌸 EXAMPLES 🌸

Wanna send a document back to the browser and show it (i.e. display it)? Say less:

send-file "/home/golf/files/myfile.jpg" headers content-type "image/jpg"

An example to display a PDF document:

set-string pdf_doc="/home/mydir/myfile.pdf"
send-file pdf_doc headers content-type "application/pdf"

And if you want to send a file for download (with the dialog), use the "download" clause. This way the document is not displayed — instead the "Save As" (or similar) window shows up. For example, to download a "PDF" document:

send-file "/home/user/file.pdf" headers download content-type "application/pdf"

👀 SEE ALSO 👀

Web

call-web out-header send-file silent-header — and See all documentation ✨

Okay that's the whole page, bestie 💜 this one's from the GOLF(2gg) crew, dated $DATE, running version $VERSION — Development era, iconic behavior, no cap. Now go send that file. 🎀✨

📦 where this page comes from