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.10.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Optional Features

[dependencies]
spikard-core = { version = "0.10.1", 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.

spikard-core 0.10.1