http.session.file

import http.session.file

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.session.file.* needs import http.session.file.

The session store that keeps one file per session.

It is the default because it needs nothing set up: no database, no daemon, no schema. It is also shared, which matters the moment a server runs on more than one core - http.serve() puts every worker in its own isolate, and a store held in memory would give each of them a different set of sessions.

Constants

SUFFIX

http.session.file.SUFFIX = '.session'

DIRECTORY_MODE

http.session.file.DIRECTORY_MODE = 448

FILE_MODE

http.session.file.FILE_MODE = 384

Functions

default_directory()

http.session.default_directory() -> string

The directory sessions are kept in when a FileStore is not told where to put them: a private subdirectory of the platform’s temporary directory, named after the working directory of the program that asked.

The temporary directory itself is deliberately not used. It is world-writable, and on a shared machine world-readable, so a session file dropped straight into it can be read by every other account on the host - which is the oldest way there is to be logged in as somebody else. The subdirectory is created 0700 and checked before it is used.

Naming it after the working directory keeps two programs on one machine from sharing a session space by accident, and keeps the same program’s sessions across a restart.

Returns string

Note: The platform’s temporary directory is cleared on a schedule the platform decides, and on most of them at every reboot. Sessions kept here therefore survive a restart of the server but not necessarily a restart of the machine. Anything that has to outlive the host names its own directory.

Classes

FileStore

class http.session.FileStore < SessionStore

Keeps each session in its own file, named after the session’s storage key.

import http.session

server.use(session.session({
  store: session.FileStore('/var/lib/app/sessions'),
}))

A file holds its expiry on the first line and the payload on the rest, so a sweep can decide whether to keep a session without understanding what is in it.

Writing

A write goes to a uniquely named file in the same directory and is then renamed over the real one, which the filesystem does atomically. A reader therefore sees either the previous session or the new one, never a half-written mixture, and a server killed mid-write leaves the previous session intact.

Two requests writing the same session at the same moment - the usual cause being parallel requests from one browser tab - both succeed, and the one that renames last is the one that survives. Nothing here serialises them.

Permissions

A session file is a bearer credential in the same way the cookie is. The directory is created 0700 and each file 0600, and a directory that anyone outside the owner can reach is refused outright rather than used. Pass strict_permissions: false to accept one anyway, which is occasionally what a deployment with its own access control wants and is never what a default should do.

On Windows the mode check does not run, because the mode a file reports there does not describe who can open it.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

http.session.FileStore(directory: ?string, options: ?dict)

Parameters

• directory (?string) — where to keep the files; defaults to default_directory(). Created, with every parent it needs, if it is not already there
• options (?dict) — gc_probability (default 0.01) and strict_permissions (default true)

Raises SessionError if the directory cannot be created, is not a directory, or is reachable by users other than its owner

FileStore.directory()

http.session.FileStore.directory() -> string

The directory the sessions are in.

Returns string

FileStore.read()

http.session.FileStore.read(key: string)

FileStore.write()

http.session.FileStore.write(key: string, payload: string, expires_at: number)

FileStore.destroy()

http.session.FileStore.destroy(key: string)

FileStore.gc()

http.session.FileStore.gc(now: number)

FileStore.to_string()

http.session.FileStore.to_string()

2026, Richard Ore and Zuri contributors