Crate helios_persistence 

Helios FHIR Server Persistence Layer

This crate provides a polyglot persistence layer for storing and retrieving FHIR resources. It supports multiple database backends via feature flags and provides configurable multitenancy with full FHIR search capabilities.

Features

• Multiple Backends: SQLite, PostgreSQL, Cassandra, MongoDB, Neo4j, Elasticsearch, S3
• Multitenancy: Three isolation strategies (shared schema, schema-per-tenant, database-per-tenant)
• Full FHIR Search: All parameter types, modifiers, chaining, _include/_revinclude
• Versioning: Full resource history with optimistic locking
• Transactions: ACID transactions with bundle support

Backend Features

Enable backends with feature flags in Cargo.toml:

[dependencies]
helios-persistence = { version = "0.1", features = ["postgres", "R4"] }

Available backend features:

• sqlite (default) - SQLite with in-memory and file modes
• postgres - PostgreSQL with JSONB storage
• cassandra - Apache Cassandra via cdrs-tokio
• mongodb - MongoDB document storage
• neo4j - Neo4j graph database
• elasticsearch - Elasticsearch for full-text search
• s3 - AWS S3 object storage

FHIR version features:

• R4, R4B, R5, R6

Architecture

The persistence layer is organized into several modules:

• tenant - Multi-tenant support with mandatory tenant context
• types - Core types for stored resources and search
• error - Error types for all operations
• core - Storage traits and abstractions
• strategy - Tenancy isolation strategies (shared schema, schema-per-tenant, database-per-tenant)
• backends - Backend implementations (SQLite, PostgreSQL, etc.)

Quick Start

use helios_persistence::tenant::{TenantContext, TenantId, TenantPermissions};
use helios_persistence::types::StoredResource;
use helios_fhir::FhirVersion;
use serde_json::json;

// Create a tenant context (required for all operations)
let tenant = TenantContext::new(
    TenantId::new("my-organization"),
    TenantPermissions::full_access(),
);

// Create a stored resource
let resource = StoredResource::new(
    "Patient",
    "patient-123",
    tenant.tenant_id().clone(),
    json!({
        "resourceType": "Patient",
        "id": "patient-123",
        "name": [{"family": "Smith", "given": ["John"]}]
    }),
    FhirVersion::default(),
);

// The resource includes persistence metadata
assert_eq!(resource.version_id(), "1");
assert_eq!(resource.url(), "Patient/patient-123");

Multitenancy

All storage operations require a TenantContext, ensuring tenant isolation at the type level. There is no way to bypass this requirement.

use helios_persistence::tenant::{TenantContext, TenantId, TenantPermissions, Operation};

// Full access tenant
let admin_ctx = TenantContext::new(
    TenantId::new("acme"),
    TenantPermissions::full_access(),
);

// Read-only tenant
let reader_ctx = TenantContext::new(
    TenantId::new("acme"),
    TenantPermissions::read_only(),
);

// Check permissions
assert!(admin_ctx.check_permission(Operation::Create, "Patient").is_ok());
assert!(reader_ctx.check_permission(Operation::Create, "Patient").is_err());

Search

Build search queries with full FHIR search support:

use helios_persistence::types::{
    SearchQuery, SearchParameter, SearchParamType, SearchValue,
    SearchModifier, SortDirective, IncludeDirective, IncludeType,
};

// Simple search
let query = SearchQuery::new("Patient")
    .with_parameter(SearchParameter {
        name: "name".to_string(),
        param_type: SearchParamType::String,
        modifier: Some(SearchModifier::Contains),
        values: vec![SearchValue::eq("smith")],
        chain: vec![],
        components: vec![],
    })
    .with_sort(SortDirective::parse("-_lastUpdated"))
    .with_count(20);

// With _include
let query_with_include = SearchQuery::new("Observation")
    .with_include(IncludeDirective {
        include_type: IncludeType::Include,
        source_type: "Observation".to_string(),
        search_param: "patient".to_string(),
        target_type: Some("Patient".to_string()),
        iterate: false,
    });

Re-exports

pub use error::StorageError;

pub use error::StorageResult;

pub use tenant::TenantContext;

pub use tenant::TenantId;

pub use tenant::TenantPermissions;

pub use types::Pagination;

pub use types::SearchQuery;

pub use types::StoredResource;

pub use core::Backend;

pub use core::BackendKind;

pub use core::CapabilityProvider;

pub use core::ResourceStorage;

pub use core::SearchProvider;

pub use core::Transaction;

pub use core::TransactionProvider;

pub use core::VersionedStorage;

pub use strategy::DatabasePerTenantConfig;

pub use strategy::DatabasePerTenantStrategy;

pub use strategy::IsolationLevel;

pub use strategy::SchemaPerTenantConfig;

pub use strategy::SchemaPerTenantStrategy;

pub use strategy::SharedSchemaConfig;

pub use strategy::SharedSchemaStrategy;

pub use strategy::TenancyStrategy;

pub use strategy::TenantResolution;

pub use strategy::TenantResolver;

Modules

advisor

Configuration Advisor for Composite Storage.

backends

Database backend implementations.

composite

Composite Storage for Polyglot Persistence

core

Core storage traits and abstractions.

error

Error types for the persistence layer.

search

FHIR Search Parameter Management and Extraction.

strategy

Multitenancy strategy implementations.

tenant

Tenant management for multi-tenant FHIR storage.

types

Core types for the persistence layer.

Constants

NAME

Crate name.

VERSION

Crate version.