Imported from HeliosSoftware/hfs (.claude/skills/run-hfs-server/SKILL.md). Install upstream with npx skills add HeliosSoftware/hfs --skill run-hfs-server. Copyright stays with the author.

HFS Server

Use this when working with the helios-hfs binary or HFS runtime configuration.

Running

# Default: R4, SQLite, port 8080
cargo run --bin hfs

# PostgreSQL
HFS_STORAGE_BACKEND=postgres HFS_DATABASE_URL="postgresql://user:pass@localhost/fhir" cargo run --bin hfs

# SQLite plus Elasticsearch
HFS_STORAGE_BACKEND=sqlite-es HFS_ELASTICSEARCH_NODES="http://localhost:9200" cargo run --bin hfs

# S3, requires the s3 feature
HFS_STORAGE_BACKEND=s3 HFS_S3_BUCKET=my-bucket cargo run --bin hfs --features s3

# Environment overrides
HFS_SERVER_PORT=3000 HFS_LOG_LEVEL=debug cargo run --bin hfs

Server Environment

Limits

Compression

hfs, sof-server, and hts accept gzip, deflate, br, and zstd request bodies via Content-Encoding. Unsupported encodings return 415. Responses are compressed when the client sends Accept-Encoding; Content-Encoding and Vary: Accept-Encoding are set. Body-size limits are enforced on decompressed bodies. SOF does not recompress application/parquet or application/zip.

CORS

Storage

Use HFS_COMPOSITE_SYNC_MODE=synchronous and HFS_ELASTICSEARCH_WRITE_REFRESH=wait_for when callers need read-your-write search semantics, such as integration tests or bulk loads that immediately search. Either alone still leaves a window: synchronous mode only guarantees the document reached Elasticsearch, and it is not searchable until the next index refresh. See crates/persistence/README.md (Search visibility on Elasticsearch-backed composites).

Storage Backends

S3 requires --features s3:

cargo build -p helios-hfs --features s3
HFS_STORAGE_BACKEND=s3 HFS_S3_BUCKET=my-bucket HFS_S3_REGION=us-east-1 cargo run --bin hfs --features s3

The standard AWS credential chain applies. For S3-compatible endpoints, set HFS_S3_ENDPOINT and HFS_S3_FORCE_PATH_STYLE=true. One HFS process shares a single AWS credential chain, so a MinIO primary store and real-AWS bulk-export output store cannot be combined in the same process.

S3 requires conditional writes

The S3 backend depends on conditional PutObject (If-Match and If-None-Match: *) for correctness — not only for /_user/settings, but for FHIR resource create, update, and delete, which use it for optimistic locking.

AWS S3, MinIO, Cloudflare R2, and recent Ceph RGW support it. Google Cloud Storage's S3-interop API and Backblaze B2 do not, and are therefore unsupported as an HFS primary store. A store that rejects the precondition headers fails loudly; one that silently ignores them would turn every concurrent write into a lost update with no error anywhere, so verify support before pointing HFS at an unfamiliar S3-compatible provider.

S3 key prefixes (IAM)

The backend writes under these prefixes inside HFS_S3_BUCKET (each below the optional HFS_S3_PREFIX):

The last two are cross-tenant and sit outside any tenant prefix. A least-privilege bucket policy scoped only to the FHIR prefixes will pass startup validation (which only issues HeadBucket) and then return AccessDenied — a 500 on every affected request. Grant the policy these prefixes too.

Note also that a bucket-wide lifecycle rule (expiration or Glacier transition) will apply to _system.user-settings/ as well: expiry silently resets users' preferences, and a Glacier transition makes them unreadable. Scope lifecycle rules to the FHIR prefixes.

Per-user UI settings

GET/PUT/PATCH /_user/settings stores an opaque, per-user JSON document (UI theme, default tenant, saved and recent queries, and each sidebar rail's rails.<page> last-selection/recents, see /work-with-ui). It is keyed by user only, never by tenant. Responses carry a weak ETag (W/"{version}"); clients may send If-Match on a write for optimistic concurrency.

Tenant scoping inside the document (#313)

The row is keyed by user, but most of what a client stores is derived from one tenant's data — a saved query like Patient?name=smith&birthdate=1970-01-01 is a PHI-bearing string. Those keys are therefore stored under a reserved byTenant map so purge_tenant_data can reach them; only theme, nav, fhirVersion and tenantId stay user-global.

The wire format is unchanged — the server projects on read and scopes on write, so clients still see a flat document and need no changes. Two operational consequences:

• Saved queries and recent searches now change when a user switches tenants. That is the intended semantics (a query saved against acme is meaningless in beta), but it will be reported as "my queries disappeared" if unannounced.
• Deleting a tenant with ?purge=true now also erases that tenant's saved and recent queries from every user's settings document, on all four backends and through both the /admin/tenants API and the /ui/tenants page. The document itself survives — it holds other tenants' content and the user's global preferences — and its version is bumped, so a client holding a stale ETag gets a 412 and re-reads rather than writing the purged content back.

A document written before this existed keeps working: it is still readable, the first write files its keys under the tenant it recorded in tenantId (or the writing tenant if it never recorded one), and a purge sweeps any that remain unattributed. Sending byTenant in a request body is rejected with 422.

Supported on the SQLite, PostgreSQL, MongoDB, and S3 backends. Elasticsearch is search-only and never a standalone primary, so an Elasticsearch-only deployment gets an explained 501 Not Implemented. On S3 the store is also unavailable (and reports the same 501) in bucket-per-tenant mode with no default system bucket, since there is nowhere tenant-independent to keep a user-global document.

When authentication is disabled, every caller resolves to the same fallback user key (l2:) and therefore shares one settings document. When auth is enabled, each caller's key is derived injectively from the token's iss and sub (u2:{iss_len}:{iss}:{sub}); a document written under the pre-#270 iss|sub encoding is migrated to the new key on first access.

Multi-tenancy

# Via header, default
curl -H "X-Tenant-ID: clinic-a" http://localhost:8080/Patient

# Via URL path, requires HFS_TENANT_ROUTING_MODE=url_path or both
curl http://localhost:8080/clinic-a/Patient

Behavior

Resource Validation

FHIR Schema based validation (helios-fhir-validator). $validate is always available (POST /[type]/$validate, GET|POST /[type]/[id]/$validate); these settings gate the write path and tune the shared service. Stored StructureDefinitions (per tenant) become validatable profiles on write.

Note: tenant profile registries are in-memory and populated by StructureDefinition writes since process start (no startup warm-load yet).

API Endpoints

$purge (permanent, irreversible deletion including history) and $reindex (rebuild the search index) are administrative, non-FHIR operations. They require the system/purge / system/reindex scopes, never ordinary resource scopes. AuditEvent can never be purged. $reindex returns 501 on the s3 backend standalone (no search index exists to rebuild) and its job state is per-process, so poll the node you kicked off against. See the helios-rest README.