prefix-register 0.1.1

A PostgreSQL-backed namespace prefix registry for CURIE expansion and prefix management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# prefix-register

[![Crates.io](https://img.shields.io/crates/v/prefix-register.svg)](https://crates.io/crates/prefix-register)
[![Documentation](https://docs.rs/prefix-register/badge.svg)](https://docs.rs/prefix-register)
[![License](https://img.shields.io/crates/l/prefix-register.svg)](LICENSE)

**Status: Beta** - API may change before 1.0 release.

A PostgreSQL-backed namespace prefix registry for [CURIE](https://www.w3.org/TR/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`:

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

## Database Setup

Create the namespaces table in your PostgreSQL database:

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

## Usage

```rust
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