Options

Holster() takes an optional options object, similar to the options GunDB accepts:

const holster = Holster({indexedDB: true, secure: true})

There are also two shorthands for connecting to relays. A string is used as the address of a single relay, and an array connects to every address provided. Both are the same as passing a peers option:

Holster("wss://relay.example.com")
Holster(["wss://relay-1.example.com", "wss://relay-2.example.com"])

Core

Option

Default

Description

peers

["ws://localhost:8765"]

Relays to connect to. Addresses need to start with ws:// or wss://, Holster doesn't add the scheme for you.

secure

false

Only write updates to disk if they're signed by a user. Set this on a relay so data can only be changed through the User API.

Storage

Option

Default

Description

file

radata

Directory used for storage in Node.js, Deno and Bun. In the browser it's the name of the IndexedDB database.

indexedDB

false

Store data in IndexedDB in the browser. Without it, the browser keeps data in memory only and relies on the relay for storage.

store

A custom storage interface, an object with get(file, cb), put(file, data, cb) and list(cb) functions. Replaces the default file system or IndexedDB storage.

userLimit

false

Enables per-user storage limits on a relay, see Storage limits.

defaultLimit

1

The storage limit in MB for each user when userLimit is set. 0 blocks storing user data unless the account is listed in .user_limit.json.

Radisk

These control how data is written to disk, by the storage layer Holster inherited from Porting Gun.

Option

Default

Description

batch

100

Number of writes to batch together before writing to disk.

write

1

Milliseconds to wait before writing a batch.

size

1MB

Maximum size of each file on disk, in bytes.

memoryLimit

500

Memory in MB used to cache files read from disk.

maxGraphSize

10000

Nodes kept in the in-memory graph before the oldest are evicted.

log

console.log

Function used to log storage errors.

Network

Option

Default

Description

port

Port to run a WebSocket server on, which makes this instance a relay.

server

An existing HTTP server to attach the WebSocket server to.

wss

An existing WebSocket server, mainly used for testing.

maxConnections

1000

Maximum number of WebSocket connections a relay accepts.

maxMessageSize

1MB

Maximum size of a message sent over WebSockets, in bytes.

maxQueueLength

10000

Maximum number of messages a client queues while waiting to send them.

Running a relay

The defaults are conservative to suit the browser. On a relay, increase them to match your server's resources:

Holster({
  port: 8765,
  secure: true,
  userLimit: true,
  defaultLimit: 10,
  maxGraphSize: 100000,
  memoryLimit: 2048,
})

Storage limits

With userLimit set, a relay tracks how much each account stores and rejects writes that would take it over its limit. Every account gets defaultLimit MB, and you can give individual accounts more by listing their public keys in a .user_limit.json file:

{"public-key-1": 5, "public-key-2": 10}

This gives the two accounts 5MB and 10MB respectively. The file goes in the directory that contains your storage directory, the file option. With the default radata, that's the directory your relay runs in. The relay reads it again every minute, so changes apply without a restart. An entry that isn't a number falls back to defaultLimit.

Holster tracks usage in a .user_storage.json file in the same directory, in bytes. To see the accounts using the most storage, run this in that directory:

npx holster-user-storage

It shows 10 accounts at a time. Pass a different directory as an argument, and use --limit and --offset to page through the list:

npx holster-user-storage /path/to/relay --limit 20 --offset 20

A write that doesn't increase an account's usage, such as a delete, is always accepted, so an account over its limit can still remove data to get back under it.