Skip to content

Asset directories

An asset directory holds files by path: installers, archives, scripts, anything a machine downloads by name. A file is fetched with a plain GET on /endpoints/{directory}/content/{path}, with Range for a resumed download and ETag for a cache that already has it, so curl, Invoke-WebRequest or an Ansible win_get_url task is all a client needs.

Every file downloads, whatever its type: a directory is a store of assets a machine fetches, not a viewer for documents or pictures. Opening one from the browse page saves it rather than showing it, and nothing uploaded can run as a page of this site.

An asset directory: folders and a file with their sizes and types, the download URL to copy, and export as zip or tar.gz

Two kinds of content

FiGet's own storage A folder on the server
Where the files are On FiGet's storage volume, one record per file In the folder itself, as it is: nothing copied, nothing indexed
How files get in Drag and drop in the browser, an authenticated upload (multipart for very large files), a zip or tar.gz unpacked into a folder, or fetched by the server from a URL Written to the folder directly, over SMB, by an application or by a person; through FiGet only when its writes are switched on
Hashes MD5, SHA-1, SHA-256 and SHA-512, recorded at upload None: the ETag comes from the size and modified time
Fits A curated set of files people upload A share that applications and people already write to, published for download

A file placed in a folder-backed directory is served at once, and a file deleted from it is gone.

A folder on the server

There are two ways to give a directory a folder, one for each person who decides:

  • Chosen on the pages. The operator mounts the shares under one folder, set as FiGet:Assets:SharesRoot, one sub-folder per share. An administrator then picks a sub-folder by name: under Content on the create form, or in the Content section of the directory's settings page, which also moves a directory onto a folder, between folders, or back to FiGet's own storage. Moving a directory off a folder never touches the folder.
  • Set in configuration. FiGet:Feeds:N:Folder names any path for a directory, and is applied again at every start. A directory with a folder from configuration shows no chooser.

The pages offer names and never take a path, so a page cannot publish a folder the operator did not mount. Only real sub-folders are offered: no links, nothing hidden or system.

A compose example with one share:

services:
  figet:
    environment:
      FiGet__Assets__SharesRoot: /shares
    volumes:
      - /srv/shares/scripts:/shares/scripts:ro

On Kubernetes or OpenShift the same folder is a ReadWriteMany volume mounted under the shares root.

Some things in a folder are never listed or served: hidden and system files, web.config, Thumbs.db, desktop.ini, Office ~$ lock files, and any link that leads out of the folder. In a Linux container a folder counts as hidden when its name starts with a dot.

Writes through FiGet are off by default for a folder: the share's own permissions decide who writes. Switched on, uploads, new folders and deletes act on the folder, and an upload is written to a temporary file and renamed into place, so a client never downloads a half-written file.

Who may download, and who may list

Two switches per directory:

  • Anyone can download a file without a token. Whoever has a file's exact address gets the file.
  • Anyone can list and browse the folders without a token.

A consumer that knows the paths it fetches needs only the first. With listing off, a folder's address and a wrong path answer the same 404, so there is nothing to discover, and listing needs a signed-in account or a key with Read.

A consumer can also get a key of its own: a read-only key limited to that one directory, sent as an X-ApiKey header or as the password of Basic authentication. That gives a way to revoke one consumer and a name on its downloads in the logs. Writing never works without credentials, whatever the switches say.

Allowed networks

A directory's settings page takes a list of addresses and ranges (10.0.0.0/8, 2001:db8::/32). A request from anywhere else is refused with 403, whatever key or account it carries. Behind a reverse proxy the address is the one the proxy forwards (see Running in production).

Sometimes one file has to reach a machine or a person that has no key and no account, and opening the directory to everyone for it is too much. A download link does that for one file: an address that downloads it without credentials, until the link ends.

Who makes one. An account or a key that may publish to the directory. Reading is not enough: a link hands the file to someone the directory does not know, and that is a decision about what the directory gives out.

On the browse page, a file's row has a Link button. It makes a link that lives for the default time and shows it with a copy button.

From a script, with the lifetime in hours:

$link = Invoke-RestMethod -Method Post "https://packages.example/endpoints/installers/link/agents/setup.msi?hours=4" `
    -Headers @{ 'X-ApiKey' = $key }
$link.url          # https://packages.example/share/CfDJ8...
$link.expiresUtc   # when it stops working

Whoever has the link has the file, so treat it like the file itself. What limits it:

  • It ends. After the lifetime it was made with, at most a week unless the server is configured otherwise.
  • It is for the file as it was. Replace the file and the link stops working; it was given for the old content, not for whatever is at that path later. Delete the file, or the directory, and it stops too.
  • Allowed networks still apply. A link does not move where a directory may be reached from.
  • It says nothing by itself. The address names no directory and no path, and every link that does not open a file gives the same answer, whether it expired, was mistyped or never existed.

One link cannot be taken back on its own: nothing is stored per link, which is also why every replica honours a link any of them made. To end one early, replace or delete the file. To end all of them, an operator sets FiGet:Assets:ShareLinks:MaxHours to 0, which also switches the feature off.

Making a link and each use of one are in the audit log (asset.link.create, asset.link.use), the use with the address it came from. The log names a link by a short fingerprint and never holds the link itself.

Cache modes per folder

Set on the browse page, per folder:

Mode Sends
Inherit What the folder above says; the directory's root defaults to no cache header
No store Cache-Control: no-store, no-cache, must-revalidate, Pragma: no-cache, Expires: -1
Max age Cache-Control: public, max-age=N

The nearest folder above a file decides, and a file's own cache metadata wins over its folders. The modes are a fixed set rather than free-form headers, so no setting can switch off the protective headers every download carries.

What a download carries

Every download is served so that nothing in it can run as part of the site: X-Content-Type-Options: nosniff, a sandboxing content security policy, and Content-Disposition: attachment on every file, under its own name. Download clients ignore these headers. The one visible difference is that a browser saves a file instead of opening it.