OxiRS Fuseki

SPARQL 1.1/1.2 HTTP server with Apache Fuseki compatibility

Status: Alpha Release (v0.1.0-alpha.3) - Released October 12, 2025

⚠️ Alpha Software: This is an early alpha release. APIs may change without notice. Not recommended for production use.

Overview

oxirs-fuseki is a high-performance SPARQL HTTP server that provides complete compatibility with Apache Jena Fuseki while leveraging Rust's performance and safety. It implements the SPARQL 1.1 Protocol for RDF over HTTP and extends it with SPARQL 1.2 features.

Features

• SPARQL Protocol Compliance: Full SPARQL 1.1 Protocol implementation
• SPARQL 1.2 Support: Extended features and optimizations
• Fuseki Compatibility: Drop-in replacement for Apache Fuseki
• Multi-Dataset Support: Host multiple datasets on different endpoints
• Authentication & Authorization: Flexible security framework
• GraphQL Integration: Dual protocol support (SPARQL + GraphQL)
• Real-time Features: WebSocket subscriptions and live queries
• High Performance: Async I/O with Tokio and optimized query execution
• Monitoring: Built-in metrics, logging, and health checks
• Configuration: YAML/TOML configuration with hot-reload

Installation

As a Library

[dependencies]
oxirs-fuseki = "0.1.0-alpha.3"

As a Binary

# Install from crates.io
cargo install oxirs-fuseki

# Or build from source
git clone https://github.com/cool-japan/oxirs
cd oxirs/server/oxirs-fuseki
cargo install --path .

Docker

docker pull ghcr.io/cool-japan/oxirs-fuseki:latest
docker run -p 3030:3030 ghcr.io/cool-japan/oxirs-fuseki:latest

Quick Start

Basic Server

use oxirs_fuseki::{Server, Config, Dataset};
use oxirs_core::Graph;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a dataset with some data
    let mut dataset = Dataset::new();
    let graph = Graph::new();
    dataset.set_default_graph(graph);
    
    // Configure the server
    let config = Config::builder()
        .port(3030)
        .host("localhost")
        .dataset("/dataset", dataset)
        .build();
    
    // Start the server
    let server = Server::new(config);
    server.run().await
}

Configuration File

Create fuseki.yaml:

server:
  host: "0.0.0.0"
  port: 3030
  cors: true
  
datasets:
  - name: "example"
    path: "/example"
    type: "memory"
    services:
      - type: "sparql-query"
        endpoint: "sparql"
      - type: "sparql-update"  
        endpoint: "update"
      - type: "graphql"
        endpoint: "graphql"
        
security:
  authentication:
    type: "basic"
    users:
      - username: "admin"
        password: "password"
        roles: ["admin"]
        
logging:
  level: "info"
  format: "json"

Run with configuration:

oxirs-fuseki --config fuseki.yaml

API Endpoints

SPARQL Query

POST /dataset/sparql
Content-Type: application/sparql-query

SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

SPARQL Update

POST /dataset/update
Content-Type: application/sparql-update

INSERT DATA { 
  <http://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .
}

GraphQL

POST /dataset/graphql
Content-Type: application/json

{
  "query": "{ person(id: \"alice\") { name, age } }"
}

Data Upload

PUT /dataset/data
Content-Type: text/turtle

@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://example.org/alice> foaf:name "Alice" .

Advanced Features

Multi-Dataset Hosting

use oxirs_fuseki::{Server, Config, Dataset};

let config = Config::builder()
    .dataset("/companies", Dataset::from_file("companies.ttl")?)
    .dataset("/products", Dataset::from_file("products.nt")?)
    .dataset("/users", Dataset::memory())
    .build();

Authentication

use oxirs_fuseki::{Config, auth::{BasicAuth, JwtAuth}};

let config = Config::builder()
    .auth(BasicAuth::new()
        .user("admin", "secret", &["admin"])
        .user("user", "password", &["read"]))
    .build();

Custom Extensions

use oxirs_fuseki::{Server, Extension, Request, Response};

struct MetricsExtension;

impl Extension for MetricsExtension {
    async fn before_query(&self, req: &Request) -> Result<(), Response> {
        // Log query metrics
        Ok(())
    }
    
    async fn after_query(&self, req: &Request, response: &mut Response) {
        // Add timing headers
    }
}

let server = Server::new(config)
    .extension(MetricsExtension);

WebSocket Subscriptions

const ws = new WebSocket('ws://localhost:3030/dataset/subscriptions');

ws.send(JSON.stringify({
  type: 'start',
  payload: {
    query: 'SUBSCRIBE { ?s ?p ?o } WHERE { ?s ?p ?o }'
  }
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New triple:', data);
};

Performance

Benchmarks

Performance Comparison

Scalability Benchmarks

Benchmarks run on AWS c5.4xlarge instance (16 vCPU, 32GB RAM)

Optimization Tips

use oxirs_fuseki::Config;

let config = Config::builder()
    // Enable query caching
    .query_cache(true)
    .cache_size(1000)
    
    // Optimize for read-heavy workloads
    .read_threads(8)
    .write_threads(2)
    
    // Enable compression
    .compression(true)
    
    .build();

Monitoring

Metrics Endpoint

GET /metrics

Returns Prometheus-compatible metrics:

# HELP sparql_queries_total Total number of SPARQL queries
# TYPE sparql_queries_total counter
sparql_queries_total{dataset="example",type="select"} 1234

# HELP sparql_query_duration_seconds Query execution time
# TYPE sparql_query_duration_seconds histogram
sparql_query_duration_seconds_bucket{le="0.1"} 800
sparql_query_duration_seconds_bucket{le="1.0"} 950
sparql_query_duration_seconds_sum 45.2
sparql_query_duration_seconds_count 1000

Health Checks

GET /health

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime": "2h 15m 30s",
  "datasets": {
    "example": {
      "status": "ready",
      "triples": 15420,
      "last_update": "2025-01-15T10:30:00Z"
    }
  }
}

Integration

With oxirs-gql

use oxirs_fuseki::Server;
use oxirs_gql::GraphQLService;

let server = Server::new(config)
    .service("/graphql", GraphQLService::new(schema));

With oxirs-stream

use oxirs_fuseki::Server;
use oxirs_stream::EventStream;

let server = Server::new(config)
    .event_stream(EventStream::kafka("localhost:9092"));

Deployment

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: oxirs-fuseki
spec:
  replicas: 3
  selector:
    matchLabels:
      app: oxirs-fuseki
  template:
    metadata:
      labels:
        app: oxirs-fuseki
    spec:
      containers:
      - name: oxirs-fuseki
        image: ghcr.io/cool-japan/oxirs-fuseki:latest
        ports:
        - containerPort: 3030
        env:
        - name: RUST_LOG
          value: "info"
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Docker Compose

version: '3.8'
services:
  fuseki:
    image: ghcr.io/cool-japan/oxirs-fuseki:latest
    ports:
      - "3030:3030"
    volumes:
      - ./data:/data
      - ./config.yaml:/config.yaml
    environment:
      - OXIRS_CONFIG=/config.yaml
      - RUST_LOG=info

Performance Tuning

Memory Optimization

# config.yaml
server:
  memory:
    query_cache_size: "1GB"    # Adjust based on available RAM
    result_cache_size: "512MB"
    connection_pool_size: 100
    
optimization:
  enable_query_planning: true
  enable_join_reordering: true
  enable_filter_pushdown: true
  parallel_execution: true
  worker_threads: 8              # Match CPU cores

High-Throughput Configuration

server:
  port: 3030
  workers: 16                    # For CPU-intensive workloads
  keep_alive: 30s
  request_timeout: 60s
  
network:
  tcp_nodelay: true
  socket_reuse: true
  backlog: 1024
  
caching:
  query_cache: true
  result_cache: true
  ttl: 3600                      # 1 hour

Production Deployment

security:
  tls:
    cert_file: "/etc/ssl/certs/server.crt"
    key_file: "/etc/ssl/private/server.key"
  rate_limiting:
    requests_per_minute: 1000
    burst_size: 100
    
logging:
  level: "warn"                  # Reduce log verbosity
  format: "json"
  audit: true
  
monitoring:
  metrics: true
  health_checks: true
  profiling: false               # Disable in production

Troubleshooting

Common Issues

Q: High memory usage with large datasets A: Enable streaming mode and adjust cache sizes:

query_execution:
  streaming_threshold: 10000     # Stream results > 10k rows
  max_memory_per_query: "100MB"

Q: Slow query performance A: Enable query optimization and check index usage:

optimization:
  query_planner: "advanced"
  statistics_collection: true
  index_recommendations: true

Q: Connection timeouts A: Adjust timeout settings and connection limits:

server:
  connection_timeout: 30s
  keep_alive_timeout: 60s
  max_connections: 1000

Debug Mode

# Enable debug logging
RUST_LOG=oxirs_fuseki=debug oxirs-fuseki --config config.yaml

# Enable query tracing
oxirs-fuseki --config config.yaml --trace-queries

# Profile performance
oxirs-fuseki --config config.yaml --profile

OxiRS Ecosystem

Core Components

• oxirs-core: RDF data model and core functionality
• oxirs-arq: SPARQL query engine with optimization
• oxirs-shacl: SHACL validation engine
• oxirs-star: RDF-star and SPARQL-star support

Server & Networking

• oxirs-fuseki: HTTP server (this crate)
• oxirs-gql: GraphQL interface and schema generation
• oxirs-stream: Real-time data streaming
• oxirs-federate: Federated query processing

AI & Analytics

• oxirs-vec: Vector embeddings and similarity search
• oxirs-shacl-ai: AI-powered data validation
• oxirs-rule: Rule-based reasoning engine

Integration Examples

// Full-stack semantic web application
use oxirs_fuseki::Server;
use oxirs_gql::GraphQLService;
use oxirs_stream::EventStream;
use oxirs_vec::VectorIndex;

let server = Server::new(config)
    .service("/graphql", GraphQLService::new(schema))
    .event_stream(EventStream::kafka("localhost:9092"))
    .vector_index(VectorIndex::new())
    .build();

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Status

� Alpha Release (v0.1.0-alpha.3) - October 12, 2025

Current alpha features:

• ✅ SPARQL query/update endpoints backed by persisted N-Quads datasets
• ✅ Federation (SERVICE clause) with retries, SERVICE SILENT, and result merging
• ✅ OAuth2/OIDC + JWT security with hardened headers and HSTS
• ✅ Prometheus metrics, slow-query tracing, and structured logging via SciRS2
• ✅ Multi-dataset support with auto save/load and CLI integration
• 🚧 Advanced admin UI & live reconfiguration (planned for beta)
• 🚧 Authentication system (in progress)
• 🚧 GraphQL integration (in progress)

Note: This is an alpha release. Some features are incomplete and APIs may change.