# TAG — Tigris Acceleration Gateway

TAG is a high-performance S3-compatible caching proxy for [Tigris object storage](https://www.tigrisdata.com). You deploy it between your application and Tigris, and it transparently caches objects on local NVMe storage — giving you sub-millisecond read latency without sacrificing S3 API compatibility.

You don't need to change any application code. Just point your S3 client at TAG instead of Tigris and your reads are automatically accelerated.

## Why TAG[​](#why-tag "Direct link to Why TAG")

Object storage is durable and scalable, but every read crosses the network. If you're serving ML models, running real-time analytics, or pushing data through high-throughput pipelines, those round-trips add up fast.

TAG eliminates them for repeated reads. It maintains a local RocksDB-backed cache that serves objects in microseconds instead of milliseconds. Unlike a generic HTTP cache, TAG understands S3 natively — it coalesces concurrent requests into a single upstream fetch, serves range requests from cached full objects, revalidates stale entries with conditional requests, and invalidates cache entries the moment you write or delete an object.

> **Bottom line:** One endpoint change. Zero code changes. Sub-millisecond reads.

## Use cases[​](#use-cases "Direct link to Use cases")

### ML model training[​](#ml-model-training "Direct link to ML model training")

Cache training datasets on local NVMe so multi-epoch training runs don't re-fetch data from remote storage on every epoch. The first epoch populates the cache; subsequent epochs read entirely from local storage, removing the network bottleneck without requiring you to pre-download datasets, shard data into tar archives, or adopt a new storage API. Works with PyTorch DataLoaders, S3 Connector for PyTorch, and any S3-compatible data loading library.

### Inference data caching[​](#inference-data-caching "Direct link to Inference data caching")

Cache model weights, configuration files, or other assets that inference workloads read repeatedly. Reduces cold-start latency and eliminates redundant network traffic.

### High-throughput data pipelines[​](#high-throughput-data-pipelines "Direct link to High-throughput data pipelines")

For real-time analytics or data processing pipelines that repeatedly read the same objects, TAG eliminates redundant network round-trips and serves data at local NVMe speeds.

## Performance[​](#performance "Direct link to Performance")

Benchmarked on AWS (c6in.16xlarge client, i3en.24xlarge server with NVMe storage):

| Object Size | Ops/sec | Bandwidth  | TTFB p50        |
| ----------- | ------- | ---------- | --------------- |
| 1 KiB       | 75,717  | 73.9 MiB/s | < 1 ms          |
| 100 KiB     | 33,350  | 3.2 GiB/s  | < 1 ms          |
| 1 MiB       | 10,955  | 10.7 GiB/s | Single-digit ms |
| 4 MiB       | 2,775   | 10.8 GiB/s | Single-digit ms |

TAG saturates a 100 Gbps NIC at 85+ Gbps for 1 MiB+ objects, with CPU utilization at only about 12%, leaving significant headroom for additional workloads.

info

These numbers reflect cache-warm steady state. First requests for uncached objects incur a round-trip to Tigris.

For full methodology, environment specs, and complete `warp` and `go-ycsb` results, see [Benchmarks](/docs/acceleration-gateway/benchmarks/.md).

## Key features[​](#key-features "Direct link to Key features")

* **S3-compatible API** — Standard AWS SDKs, AWS CLI, or any S3-compatible library. Path-style addressing only.
* **Transparent proxy** — TAG forwards your SigV4 credentials to Tigris as-is. It never sees or stores your secret keys.
* **Embedded RocksDB cache** — NVMe-optimized, two-key storage pattern for efficient HEAD and conditional operations.
* **Request coalescing** — Multiple concurrent requests for the same uncached object result in a single upstream fetch.
* **Range request optimization** — Range misses trigger a background fetch of the full object, so future ranges come from cache.
* **Write-through invalidation** — Writes, deletes, and copies invalidate cache entries immediately.
* **Multi-node clustering** — Gossip discovery, consistent hashing, and gRPC routing for distributed caching across nodes.

For detailed request flows, sequence diagrams, and cluster architecture, see [Architecture](/docs/acceleration-gateway/architecture/.md).

## S3 API coverage[​](#s3-api-coverage "Direct link to S3 API coverage")

TAG supports commonly used S3 operations, validated against 214 tests from the `ceph/s3-tests` compatibility suite.

| Category          | Operations                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Objects           | Get, Head, Put, Delete, Copy, Tagging, ACL                                                                               |
| Buckets           | List, Create, Delete, Head, ListV1/V2, Location, Versioning, ACL, Policy, CORS, Tagging, Lifecycle, DeleteObjects (bulk) |
| Multipart Uploads | Initiate, UploadPart, UploadPartCopy, Complete, Abort, ListParts, ListMultipartUploads                                   |
| Auth              | SigV4 headers, presigned URLs, chunked encoding                                                                          |

Not Supported

Object versioning, server-side encryption (SSE-C/S3/KMS), Object Lock, POST object (browser uploads), and virtual-hosted style addressing.

For the full compatibility matrix, see [S3 Compatibility](/docs/acceleration-gateway/s3-compatibility/.md). For client SDK examples, see [S3 Client Usage](/docs/acceleration-gateway/usage/.md).

## Cache behavior[​](#cache-behavior "Direct link to Cache behavior")

TAG adds an `X-Cache` response header to every response:

| Value         | Meaning                                                          |
| ------------- | ---------------------------------------------------------------- |
| `HIT`         | Served from cache (includes successful revalidations)            |
| `MISS`        | Fetched from Tigris, now cached                                  |
| `REVALIDATED` | Revalidated with Tigris; object changed and new content returned |
| `BYPASS`      | Cache skipped (client sent `Cache-Control: no-store`)            |
| `DISABLED`    | Caching turned off server-side                                   |

For revalidation, cache-control headers, eviction, and automatic invalidation, see [Cache Control](/docs/acceleration-gateway/cache-control/.md).

## Security[​](#security "Direct link to Security")

Your clients sign requests with their own Tigris credentials, and TAG forwards them to Tigris as-is — it never sees or stores your secret keys. After a client's first request, TAG learns derived signing keys from Tigris (encrypted with AES-256-GCM), so it can validate subsequent requests locally without calling home.

For the full authentication flow, authorization lifecycle, and credential setup, see [Security and Access Control](/docs/acceleration-gateway/security/.md).

## Monitoring[​](#monitoring "Direct link to Monitoring")

TAG exposes 30+ Prometheus metrics at `/metrics` covering request throughput, cache effectiveness, request coalescing, upstream health, authentication, and connection stats.

For the full metrics reference, PromQL examples, alerting recommendations, and scrape configuration, see [Metrics Reference](/docs/acceleration-gateway/metrics/.md).