prefix-register

Status: Beta - API may change before 1.0 release.

A PostgreSQL-backed namespace prefix registry for CURIE expansion and prefix management.

Features

Async-only - Built on tokio for high concurrency
In-memory caching - Prefixes loaded on startup for fast CURIE expansion
First-prefix-wins - Each URI can only have one registered prefix
Batch operations - Efficiently store multiple prefixes in a single round trip
PostgreSQL backend - Durable, scalable storage with connection pooling
Startup resilience - Optional retry with exponential backoff for container orchestration
Input validation - Prevents DoS via length limits (prefix max 64, URI max 2048 chars)
Tracing instrumentation - Built-in spans and events for observability (configure subscriber in your app)

Use Cases

CURIE expansion in RDF processing
Namespace prefix management for semantic web applications
Prefix discovery from Turtle, JSON-LD, XML documents

Installation

Add to your Cargo.toml:

[dependencies]
prefix-register = "0.1"
tokio = { version = "1", features = ["rt-multi-thread"] }

Database Setup

Create the namespaces table in your PostgreSQL database:

CREATE TABLE IF NOT EXISTS namespaces (
    uri TEXT PRIMARY KEY,
    prefix TEXT NOT NULL UNIQUE
);

Usage

use prefix_register::PrefixRegistry;

#[tokio::main]
async fn main() -> prefix_register::Result<()> {
    // Connect to PostgreSQL
    let registry = PrefixRegistry::new(
        "postgres://localhost/mydb",
        10,  // max connections
    ).await?;

    // Store a prefix (only if URI doesn't already have one)
    let stored = registry.store_prefix_if_new(
        "foaf",
        "http://xmlns.com/foaf/0.1/"
    ).await?;
    println!("Prefix stored: {}", stored);

    // Expand a CURIE
    if let Some(uri) = registry.expand_curie("foaf", "Person").await? {
        println!("foaf:Person = {}", uri);
        // Output: foaf:Person = http://xmlns.com/foaf/0.1/Person
    }

    // Batch store prefixes - returns detailed result for logging
    let prefixes = vec![
        ("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#"),
        ("rdfs", "http://www.w3.org/2000/01/rdf-schema#"),
        ("schema", "https://schema.org/"),
    ];
    let result = registry.store_prefixes_if_new(prefixes).await?;
    println!("Stored {}, skipped {}", result.stored, result.skipped);

    Ok(())
}

API

PrefixRegistry

new(database_url, max_connections) - Connect to PostgreSQL and load existing prefixes
new_with_retry(database_url, max_connections, retry_config) - Connect with retry logic for transient failures
get_uri_for_prefix(prefix) - Get the URI for a prefix (cache-first)
get_prefix_for_uri(uri) - Get the prefix for a URI
store_prefix_if_new(prefix, uri) - Store a prefix if the URI doesn't have one (returns bool)
store_prefixes_if_new(prefixes) - Batch store prefixes (returns BatchStoreResult)
expand_curie(prefix, local_name) - Expand a CURIE to a full URI
get_all_prefixes() - Get all registered prefix mappings
prefix_count() - Get the number of registered prefixes

RetryConfig

Configuration for startup retry behaviour:

default() - 5 retries, 1s initial delay, 30s max delay
none() - No retries (fail immediately)
new(max_retries, initial_delay, max_delay) - Custom configuration

BatchStoreResult

Returned by store_prefixes_if_new() for detailed reporting:

stored: usize - Number of new prefixes stored
skipped: usize - Number of prefixes skipped (URI already had a prefix)
total() - Total prefixes processed
all_stored() - Returns true if all were stored
none_stored() - Returns true if none were stored

License

Apache-2.0

prefix-register 0.1.1