titip

Titip

Titip is a high-throughput, low-allocation HTTP caching middleware for Go applications and API gateways.

Designed for high-concurrency services, Titip reduces backend load by serving cached responses with minimal memory allocation, atomic multi-variant negotiation, RFC-compliant freshness calculations, and fail-open resilience.

Key Features

• Low-Allocation Design: Reuses internal memory buffers and decompression streams to minimize heap allocations under high concurrency.
• Fail-Open Resilience: Storage outages, decompression errors, or upstream panics safely bypass to the origin handler (fwd=bypass) or serve stale cache without terminating the process.
• Session & Privacy Protection: Cold URL misses execute independently without singleflight coalescing, preventing accidental sharing of Set-Cookie or private session headers across concurrent callers.
• RFC-7234, RFC-9111 & RFC-9213 Compliant: Implements the official Age & Freshness calculation standard (apparent age, corrected initial age, resident time, clock-skew correction, and multi-variant Vary header negotiation).
• Tiered Cache-Control (RFC 9213): Supports targeted header resolution (Titip-Cache-Control → CDN-Cache-Control → Cache-Control), allowing backends to configure edge caching independently from browser caching.
• RFC-9211 Cache-Status Observability: Structured diagnostics (Cache-Status: titip; hit; ttl=295, fwd=stale, fwd=bypass) with multi-tier cache chaining.
• Edge Side Includes (ESI): Concurrent fragment assembly, in-process routing, recursive loop protection, and SSRF prevention.
• Granular Cache Purge API: Invalidation via programmatic Go API (exact URL, wildcard prefixes, surrogate Cache-Tag, soft-purge, or total cache wipeout).
• Pluggable Architecture: Standard net/http middleware with modular framework adapters and decoupled storage engines.

Architecture

Titip separates metadata from variant payloads to enable atomic multi-variant negotiation (Vary) and short-circuiting with zero redundant body I/O:

[ Incoming Request ] ──► (Primary Key: Scheme + Host + Path + Filtered Query)
                               │
                               ▼
        ┌──────────────────────────────────────────────┐
        │ Stage 1: GetMeta(primaryKey)                 │
        │ Evaluates: Vary headers, freshness, tags     │
        └──────────────────────┬───────────────────────┘
                               │
        ┌──────────────────────┴───────────────────────┐
        │ Match Vary Variant & Evaluate Freshness      │
        └──────┬───────────────────────────────┬───────┘
               │                               │
      (Downstream 304 / HEAD)             (Cache Hit)
               │                               │
               ▼                               ▼
    ┌─────────────────────┐       ┌──────────────────────────────┐
    │ Serve 304 / Headers │       │ Stage 2: GetVariant(pk, vk)  │
    │ (0 Body Payload I/O)│       │ Returns: Headers & Body      │
    └─────────────────────┘       └──────────────┬───────────────┘
                                                 │
                                                 ▼
                                  ┌──────────────────────────────┐
                                  │ LZ4 Decompress & Stream Body │
                                  └──────────────────────────────┘

Modules & Ecosystem

Titip is organized as a multi-module workspace. Each module is versioned independently:

Quickstart

Install the core package and Redis storage driver:

go get github.com/indragunawan/titip
go get github.com/indragunawan/titip/storage/redis

Wrap any standard net/http handler:

package main

import (
    "context"
    "net/http"
    "time"

    "github.com/redis/rueidis"

    "github.com/indragunawan/titip"
    storageRedis "github.com/indragunawan/titip/storage/redis"
)

func main() {
    // 1. Initialize Redis Client
    client, err := rueidis.NewClient(rueidis.ClientOption{
        InitAddress: []string{"127.0.0.1:6379"},
    })
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // 2. Create Titip Redis Storage
    store, err := storageRedis.New(client, storageRedis.WithKeyPrefix("titip:"))
    if err != nil {
        panic(err)
    }

    // 3. Configure Titip Engine
    cache, err := titip.New(
        store,
        titip.WithCacheStatus(titip.CacheStatusRFC9211),
        titip.WithBackgroundFetchTimeout(125*time.Second),
    )
    if err != nil {
        panic(err)
    }
    defer cache.Close(context.Background())

    // 4. Wrap Standard HTTP Handler
    mux := http.NewServeMux()
    mux.HandleFunc("GET /api/data", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        // Cache publicly for 60 seconds, allow serving stale for 5 minutes during revalidation
        w.Header().Set("Cache-Control", "public, max-age=60, stale-while-revalidate=300")
        w.Header().Set("Cache-Tag", "catalog items")
        w.Write([]byte(`{"message": "hello from origin", "timestamp": "` + time.Now().String() + `"}`))
    })

    http.ListenAndServe(":8080", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        cache.ServeHTTP(w, r, mux)
    }))
}

Configuration Reference

Initialize Titip with the mandatory storage engine and any functional options via titip.New(store storage.Storage, opts ...Option):

Cache Key & Query Parameter Normalization

Titip constructs normalized cache keys directly without expensive hashing. Use CacheKey to filter query parameters and strip tracking tags to prevent cache fragmentation:

cache, err := titip.New(
    store,
    titip.WithCacheKey(titip.CacheKey{
        // Strips marketing query parameters (utm_*, fbclid, gclid, mc_eid, etc.)
        ExcludeMarketingQueryParams: true,
        // Allowlist specific query parameters to include (or use ExcludedQueryParams for a denylist)
        IncludedQueryParams:    []string{"page", "sort", "filter"},
    }),
)

Cache-Status Diagnostics

Titip supports three Cache-Status modes configured via WithCacheStatus:

1. CacheStatusRFC9211 (Structured Header)

Emits structured diagnostics compliant with RFC 9211, supporting multi-tier cache chaining:

Cache-Status: titip; hit; ttl=240
Cache-Status: "Fastly"; hit, titip; hit; ttl=240

2. CacheStatusSimpleToken (Single Token Header)

Emits a concise single-token status header:

3. CacheStatusNone

Disables the Cache-Status response header completely.

Server-Timing Diagnostics

Titip supports the standard Server-Timing header to break down latency in browser DevTools (Chrome Network Timing tab), solving black-box TTFB:

Server-Timing: titip-status;desc="HIT", titip-meta;dur=1.49, titip-body;dur=3.39, titip;dur=4.95

Metrics Reported

[!TIP] Titip emits Server-Timing via Header.Add, preserving any existing application-level Server-Timing headers sent by upstream backends (e.g. database query timings). Browsers combine them into a unified list.

Restricting Access via Debug Cookie

To prevent exposing internal infrastructure metrics to the general public, gate header generation with a cookie:

cache, err := titip.New(
    store,
    titip.WithServerTimingCookie("debug_timing", "secret_value"),
)

Cache Invalidation & Purge API

Titip provides a programmatic Go API for Hierarchical Path Purging, Surrogate Tag Purging, and Namespace Invalidation.

Programmatic Go API

// 1. Path Purge (purges /api/products and all its query string variants)
err := cache.Purge(ctx, "/api/products")

// 2. Exact Query Invalidation (purges only ?id=10, leaves other queries intact)
err := cache.Purge(ctx, "http://example.com/api/products?id=10", titip.WithSoftPurge())

// 3. Directory Wildcard (purges all cached paths under /assets/)
err := cache.Purge(ctx, "/assets/*")

// 4. Surrogate Tag Invalidation (invalidates all cached entries matching the tag)
err := cache.PurgeTag(ctx, "catalog")

// 5. Namespace Invalidation (invalidates all cached entries under the configured prefix)
err := cache.PurgeAll(ctx)

Tiered & Targeted Cache-Control (RFC 9213)

Titip supports RFC 9213 Targeted Cache-Control, allowing backend origins to define separate caching rules for the edge/proxy layer versus end-user browsers.

Precedence Hierarchy (First Match Wins)

$$\text{\textbf{Titip-Cache-Control}} ;\longrightarrow; \text{\textbf{CDN-Cache-Control (RFC 9213)}} ;\longrightarrow; \text{\textbf{Cache-Control (RFC 9111)}}$$

HTTP/1.1 200 OK
Titip-Cache-Control: public, max-age=86400, stale-while-revalidate=3600
Cache-Control: private, no-store

• Titip (Intermediary): Caches the response in storage for 24 hours (max-age=86400), shielding the origin from load.
• Client (Browser): Receives Cache-Control: private, no-store, preventing sensitive data from persisting in local browser history.

Edge Side Includes (ESI)

Titip includes an Edge Side Includes (ESI) engine with parallel fragment fetching, circular loop protection, and SSRF prevention.

When ESI is active, Titip advertises capability to upstream origins by sending Surrogate-Capability: titip="ESI/1.0" per Edge Side Includes (ESI) specifications. Origins can respond with Surrogate-Control: content="ESI/1.0" to direct ESI processing.

For standalone package documentation and options reference, see ESI Package Guide.

cache, err := titip.New(
    store,
    titip.WithESI(
        esi.WithInternalFetcher(esi.HandlerFetcher(router)),
        esi.WithMaxDepth(3),
        esi.WithMaxTimeout(5 * time.Second),
    ),
)

Supported ESI Tags & Syntax

ESI Functional Options (esi.Option)

Observability & Metrics

Titip exports comprehensive Prometheus metrics for request traffic, cache latencies, purge invalidations, and ESI fragment processing:

// Register with a Prometheus registry:
cache, err := titip.New(
    store,
    titip.WithMetrics(prometheus.DefaultRegisterer),
)

Exported Metrics

# Example Prometheus Scrape Output:
titip_requests_total{status="hit"} 4125
titip_requests_total{status="miss"} 102
titip_requests_total{status="stale_hit"} 18
titip_requests_total{status="revalidated"} 12
titip_requests_total{status="bypass"} 5
titip_requests_total{status="error"} 0

titip_purges_total{mode="soft",status="success",type="url"} 45
titip_purged_entries_total{mode="soft",type="url"} 45

titip_esi_fragments_total{status="success"} 230
titip_esi_duration_seconds_bucket{mode="in_process",le="0.005"} 225

Testing & Concurrency Standards

Titip enforces continuous race detection and zero-leak concurrency standards:

# Run all unit and concurrency stress tests with race detector
go test -race -count=50 -v ./...

Contributing

We welcome contributions for new framework adapters and storage drivers.

Please read our Contributing Guide for architectural guidelines, interface contracts, and testing standards.

License

This project is licensed under the Apache 2.0 License.