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 |
|---|---|---|
|
| Relays to connect to. Addresses need to start with |
|
| 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 |
|---|---|---|
|
| Directory used for storage in Node.js, Deno and Bun. In the browser it's the name of the IndexedDB database. |
|
| Store data in IndexedDB in the browser. Without it, the browser keeps data in memory only and relies on the relay for storage. |
| A custom storage interface, an object with | |
|
| Enables per-user storage limits on a relay, see Storage limits. |
|
| The storage limit in MB for each user when |
Radisk
These control how data is written to disk, by the storage layer Holster inherited from Porting Gun.
Option | Default | Description |
|---|---|---|
|
| Number of writes to batch together before writing to disk. |
|
| Milliseconds to wait before writing a batch. |
| 1MB | Maximum size of each file on disk, in bytes. |
|
| Memory in MB used to cache files read from disk. |
|
| Nodes kept in the in-memory graph before the oldest are evicted. |
|
| Function used to log storage errors. |
Network
Option | Default | Description |
|---|---|---|
| Port to run a WebSocket server on, which makes this instance a relay. | |
| An existing HTTP server to attach the WebSocket server to. | |
| An existing WebSocket server, mainly used for testing. | |
|
| Maximum number of WebSocket connections a relay accepts. |
| 1MB | Maximum size of a message sent over WebSockets, in bytes. |
|
| 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:
maxConnections: connections are refused after 1000 clients, increase it to support more users.maxGraphSize: the in-memory copy of your graph. Increasing it uses more memory but makes reads faster.memoryLimit: memory used to cache storage files. A higher value means reading from disk less often, and up to half of the server's available memory improves performance.defaultLimit: the storage each account gets whenuserLimitis set, see below.
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-storageIt 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 20A 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.