# go-tileproxy

A high-performance tile proxy server written in Go, supporting multiple tile services and formats with caching capabilities.

## Features

- **Multiple Service Types**: Support for WMS, WMTS, Mapbox Vector Tiles, XYZ/OSM tiles, Cesium 3D Tiles, and ArcGIS REST services
- **Tile Formats**: PNG, JPEG, WebP, MVT, PBF, GeoJSON, Terrain, LERC
- **Caching System**: Local file-based cache with multiple layout options (TMS, Quadkey, ArcGIS, MapProxy)
- **Image Processing**: Tile merging, transformation, masking, and blank tile generation
- **Import/Export**: Support for MBTiles, GeoPackage, and COG formats
- **Reprojection**: Automatic tile reprojection between coordinate systems
- **Concurrent Processing**: Thread-safe operations with optimized performance

## Supported Services

- **MapboxService**: Mapbox Vector Tiles specification
- **WMSService**: Web Map Service (OGC standard) with GetMap and GetFeatureInfo support
- **WMTSService**: Web Map Tile Service (OGC standard)
- **TileService**: Standard XYZ/OSM tile services
- **CesiumService**: Cesium 3D Tiles specification
- **ArcGISService**: ArcGIS REST tile services

## Supported Tile Types

- `TILE_IMAGERY`: Raster image tiles (PNG, JPEG, WebP)
- `TILE_VECTOR`: Vector tiles (MVT, PBF, GeoJSON)
- `TILE_DEM`: Digital elevation model tiles (quantized mesh, terrain)

## Requirements

- Go 1.24 or higher

## Installation

```bash
go get github.com/flywave/go-tileproxy
```

## Configuration Validation & Hot Reload

Configuration can be validated and hot-reloaded without restarting the server:

- `setting.ValidateConfigJSON(data)` returns a structured, front-end friendly report (field-level errors/warnings per service) — see [docs/config-validation.md](docs/config-validation.md) for the full flywave-server integration guide.
- `proxy.ReloadFromFile(path, nil)` / `proxy.ReloadServices(services, nil)` apply a new configuration atomically; an invalid configuration never affects running services.
- `tileproxy serve --watch` watches the config file and hot-reloads on change; `tileproxy validate -c config.json` checks a config from the command line.

## HTTP Caching

Tile and capabilities responses are cache-friendly out of the box:

- Tile responses (TMS/WMTS/Cesium) carry `ETag` and `Last-Modified` and answer
  `If-None-Match` / `If-Modified-Since` with `304 Not Modified`.
- Setting `max_tile_age` additionally emits `Cache-Control: public, max-age=N, s-maxage=N`
  for CDN/browser freshness; without it clients revalidate instead.
- WMS/WMTS capabilities documents are rendered once per base URL, cached and
  revalidated via ETag, so repeated GetCapabilities requests are cheap.
- Concurrent cache-miss fetches for the same tile are collapsed by the tile
  locker (in-memory or file based), preventing thundering-herd upstream hits.

## Cache Policies

Per-cache policies decide when cached tiles are served and when the origin
sources are consulted: `cache_first` (default: serve whatever is cached until
it is cleaned), `ttl` (refresh after `ttl_hours`), `revalidate` (serve the
stale tile and refresh in the background) and `bypass` (origin only). See
[docs/cache-policy.md](docs/cache-policy.md) for the full behaviour matrix
and configuration examples.

## Usage

### Basic Example

```go
package main

import (
    "net/http"
    
    "github.com/flywave/go-tileproxy"
    "github.com/flywave/go-tileproxy/setting"
)

func main() {
    // Load configuration
    globals := &setting.GlobalsSetting{}
    services := []*setting.ProxyService{}
    cacheFactory := &setting.DefaultCacheFactory{}
    
    // Create tile proxy
    proxy := tileproxy.NewTileProxy(globals, services, cacheFactory)
    
    // Start HTTP server
    http.ListenAndServe(":8080", proxy)
}
```

### Running from Command Line

```bash
# Build the project
go build ./...

# Run tests
go test ./...

# Run the server
go run ./cmd/main.go
```

## Building

```bash
# Build all packages
go build ./...

# Build executable
go build -o tileproxy ./cmd
```

## Testing

```bash
# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for a specific package
go test ./cache
go test ./service

# Run with verbose output
go test -v ./...
```

## Linting

```bash
# Format code
go fmt ./...

# Run vet
go vet ./...
```

## Project Structure

- `cache`: Cache management and local storage
- `client`: HTTP clients for different service types
- `service`: Service implementations for each protocol
- `layer`: Layer abstractions and source management
- `imagery`: Image processing and tile manipulation
- `terrain`: Terrain and DEM tile handling
- `vector`: Vector tile processing
- `sources`: Source implementations (WMS, ArcGIS, Mapbox, etc.)
- `request`: Request parsing and routing
- `imports`: Import handlers (MBTiles, GeoPackage, archives)
- `exports`: Export handlers (MBTiles, GeoPackage, COG)
- `setting`: Configuration and settings management
- `tile`: Tile definitions and options
- `utils`: Utility functions

## Configuration

The proxy uses a configuration-based approach where services, sources, caches, and grids are defined through settings. Each service can have:

- Multiple data sources (WMS, tile servers, etc.)
- Cache configurations with different layouts
- Grid definitions for projections and tile matrices
- Legend and feature info support where applicable

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Please ensure:
- Code follows the project's style guidelines
- All tests pass
- New features include tests
- Commits are clear and descriptive