spikard-core

Shared transport-agnostic primitives and types for building Spikard runtimes across multiple languages and frameworks.

Status & Badges

Overview

spikard-core provides the foundational types and traits that enable Spikard to work across multiple language bindings:

• Request/Response models - HTTP-agnostic request and response types
• Validation primitives - JSON Schema validation and header/cookie checking
• Middleware interfaces - Traits for composable middleware stacks
• Serialization support - Efficient serialization via serde
• Error handling - Structured error types for cross-language error translation

Features

• Transport-agnostic - Works with Axum, Hyper, or any HTTP framework
• Schema validation - Built-in JSON Schema support via jsonschema crate
• Compression - Gzip and Brotli compression/decompression
• Header/Cookie handling - RFC-compliant header and cookie parsing
• URL encoding - Query string parsing and URL handling
• Zero-copy design - Efficient memory usage with minimal allocations
• Type safety - Strongly-typed request and response structures

Installation

[dependencies]
spikard-core = "0.9.2"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Optional Features

[dependencies]
spikard-core = { version = "0.9.2", features = ["di"] }

• di - Enables dependency injection support with Tokio async runtime

Quick Start

Request/Response Handling

use spikard_core::{Request, Response};
use std::collections::HashMap;

// Create a request
let mut request = Request::new(
    "GET".to_string(),
    "/api/users".to_string(),
);

// Add headers
request.headers_mut().insert(
    "Authorization".to_string(),
    "Bearer token123".to_string(),
);

// Add query parameters
let mut query = HashMap::new();
query.insert("filter".to_string(), "active".to_string());
request.set_query_params(query);

// Create a response
let mut response = Response::new(200);
response.set_body(r#"{"users": []}"#.as_bytes().to_vec());

Schema Validation

use spikard_core::validation::ValidateBody;
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
    },
    "required": ["name", "email"]
});

let body = json!({
    "name": "Alice",
    "email": "alice@example.com"
});

// Validate body against schema
validate_body(&body, &schema)?;

Compression Support

use spikard_core::compression;

let original = b"This is a long string that will be compressed";

// Gzip compression
let compressed = compression::gzip_encode(original)?;
let decompressed = compression::gzip_decode(&compressed)?;

// Brotli compression
let compressed = compression::brotli_encode(original)?;
let decompressed = compression::brotli_decode(&compressed)?;

Core Types

• Request - HTTP request model with headers, cookies, body, and path parameters
• Response - HTTP response model with status, headers, and body
• HandlerResult - Standard result type for handlers
• ValidationError - Structured validation errors with field-level details
• RequestContext - Request execution context with metadata
• RouteConfig - Route configuration with validation schemas

Architecture

spikard-core sits at the foundation of the Spikard architecture:

┌─────────────────────────────────────┐
│  Language Bindings                  │
│  (Python, Node, Ruby, PHP, WASM)    │
└──────────────┬──────────────────────┘
               │ implements
┌──────────────▼──────────────────────┐
│  spikard-http (Axum Runtime)        │
└──────────────┬──────────────────────┘
               │ uses
┌──────────────▼──────────────────────┐
│  spikard-core (Primitives)          │
└─────────────────────────────────────┘

All language bindings depend on spikard-core to ensure consistent request/response handling across platforms.

Documentation

• Main Project README
• Full API Documentation
• Architecture Decision Records

Related Crates

• spikard - High-level HTTP framework
• spikard-http - HTTP server implementation
• spikard-py - Python bindings
• spikard-node - Node.js bindings

License

MIT