go-overlay-services

module
v1.3.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0

README

🌐  go-overlay-services

Custom HTTP server for interacting with Overlay Services on the Bitcoin SV blockchain.


Release Go Version License


CI / CD    Build Last Commit      Quality    Coverage
Security    Scorecard Security      Community    Contributors Ask DeepWiki


Project Navigation
📦 Installation ✨ Features 📚 Documentation
🧪 Examples & Tests ⚡ Benchmarks 🛠️ Code Standards
🤖 AI Usage 🤝 Contributing 👥 Maintainers
📝 License

✨ Features

  • Standalone HTTP Server Operates as a self-contained server with customizable configuration and overlay engine layers.

  • OpenAPI Integration Supports OpenAPI specifications with an interactive Swagger UI for exploring and testing endpoints.

  • Flexible Configuration Formats Allows importing and exporting configuration using common formats such as .env, .yaml, and .json.

  • Real-Time Observability Provides basic real-time observability and performance monitoring out of the box.


Middleware & Built-in Components
  • Request Tracing Attaches a unique request ID to every incoming request for consistent traceability across logs and systems.

  • Idempotency Support Enables safe request retries by ensuring idempotent behavior for designated endpoints.

  • CORS Handling Manages cross-origin resource sharing (CORS) to support web applications securely.

  • Panic Recovery Catches and logs panics during request handling, with optional stack trace support.

  • Structured Request Logging Logs HTTP requests using a customizable format, including method, path, status, and errors.

  • Health Check Endpoint Exposes an endpoint for health and readiness checks, suitable for orchestration tools.

  • Performance Profiling Integrates pprof profiling tools under the /api/v1 path for runtime diagnostics.

  • Request Body Limits Enforces size limits on application/octet-stream payloads to protect against abuse.

  • Bearer Token Authorization Validates Bearer tokens found in the Authorization header of incoming HTTP requests and enforces authorization based on OpenAPI security scopes.


📦 Installation

go-overlay-services requires a supported release of Go.


Running as a Standalone Server
  1. Clone the repository

    git clone https://github.com/bsv-blockchain/go-overlay-services.git
    cd go-overlay-services
    
  2. Create a configuration file

    cp app-config.example.yaml app-config.yaml
    

    Edit app-config.yaml to customize your server settings (port, tokens, etc.)

  3. Run the server

    go run examples/srv/main.go -config app-config.yaml
    
  4. Optional: Build a binary

    go build -o overlay-server examples/srv/main.go
    ./overlay-server -config app-config.yaml
    

The server will start on http://localhost:3000 by default (or the port specified in your config).


Using as a Library

To use go-overlay-services as a library in your own Go application:

go get -u github.com/bsv-blockchain/go-overlay-services

See the examples directory for code examples showing how to:


📚 Documentation

The optional Persistence v1 contract defines admission and recovery capability types. A Storage that implements this capability alongside the legacy storage interface (as pkg/storage/mongodb's Store does) both satisfies engine.Storage and selects the engine's admission submit path at runtime. This stays opt-in: it only applies when such a store is explicitly injected into an Engine, and the default HTTP server construction still uses NoopEngineProvider.

Supported API Endpoints
HTTP Method Endpoint Description Protection
POST /api/v1/admin/startGASPSync Starts GASP synchronization Admin only
POST /api/v1/admin/syncAdvertisements Synchronizes advertisements Admin only
GET /api/v1/getDocumentationForLookupServiceProvider Retrieves documentation for Lookup Service Providers Public
GET /api/v1/getDocumentationForTopicManager Retrieves documentation for Topic Managers Public
GET /api/v1/listLookupServiceProviders Lists all Lookup Service Providers Public
GET /api/v1/listTopicManagers Lists all Topic Managers Public
POST /api/v1/lookup Submits a lookup question Public
POST /api/v1/requestForeignGASPNode Requests a foreign GASP node Public
POST /api/v1/requestSyncResponse Requests a synchronization response Public
POST /api/v1/submit Submits a transaction Public
POST /api/v1/arc-ingest Ingests a Merkle proof ARC callback token

Configuration

The server configuration is encapsulated in the Config struct with the following fields:

Field Type Description Default Value
AppName string Name of the application shown in server metadata. "Overlay API v0.0.0"
Port int TCP port number on which the server listens. 3000
Addr string Network address the server binds to. "localhost"
ServerHeader string Value sent in the Server HTTP response header. "Overlay API"
AdminBearerToken string Bearer token required for authentication on admin-only routes. Random UUID generated by default
OctetStreamLimit int64 Maximum allowed size in bytes for requests with Content-Type: application/octet-stream. 1GB (1,073,741,824 bytes)
ConnectionReadTimeout time.Duration Maximum duration to keep an open connection before forcefully closing it. 10 seconds
ARCAPIKey string API key for ARC service integration. Empty string
ARCCallbackToken string Token for authenticating ARC callback requests. Random UUID generated by default

Default Configuration

A default configuration, DefaultConfig, is provided for local development and testing, with sensible defaults for all fields.


Server Options

The HTTP server supports flexible setup via functional options (ServerOption), allowing customization during server creation:

Option Description
WithMiddleware(fiber.Handler) Adds a Fiber middleware handler to the server's middleware stack.
WithEngine(engine.OverlayEngineProvider) Sets the overlay engine provider that handles business logic in the server.
WithAdminBearerToken(string) Overrides the default admin bearer token securing admin routes.
WithOctetStreamLimit(int64) Sets a custom limit on octet-stream request body sizes to control memory usage.
WithARCCallbackToken(string) Sets the ARC callback token used to authenticate ARC callback requests on the HTTP server.
WithARCAPIKey(string) Sets the ARC API key used for ARC service integration.
WithConfig(Config) Applies a full configuration struct to initialize the Fiber app with specified settings.

Development Build Commands

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

View all build commands

magex help
Development Task Automation

This project uses a dedicated Taskfile.yml powered by the task CLI to automate common workflows. This centralizes critical operations such as testing, code generation, API documentation bundling, and code linting into a single, easy-to-use interface.

Formalizing these processes ensures:

  • Consistency across developer environments
  • Automation of chained commands and validations
  • Efficiency by reducing manual complexity
  • Reproducibility in CI/CD and local setups
  • Maintainability with centralized workflow updates
Available Tasks
  • execute-unit-tests Runs all unit tests with fail-fast, vet checks, and disables caching for fresh results.

  • oapi-codegen Generates HTTP server code and models from the OpenAPI spec to keep the API and code in sync.

  • swagger-doc-gen Bundles the OpenAPI spec into a single YAML file, ready for validation and documentation tools.

  • swagger-ui-up Bundles, validates, and starts Swagger UI with Docker Compose for interactive API exploration.

  • swagger-ui-down Stops Swagger UI services and cleans up containers.

  • swagger-cleanup Removes generated Swagger files and stops any running Swagger UI containers.

  • execute-linters Runs Go linters and applies automatic fixes to maintain code quality.

Repository Features

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via modular environment files and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.


🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.26.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

🛠️ Code Standards

Read more about this Go project's code standards.


🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with AI assistants.


👥 Maintainers

Siggi Galt MrZ
Siggi Dylan MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬.

Stars


📝 License

License

Directories

Path Synopsis
examples
config command
Package main generates a default overlay services configuration file.
Package main generates a default overlay services configuration file.
custom command
Package main demonstrates custom overlay services configuration.
Package main demonstrates custom overlay services configuration.
srv command
Package main provides an example overlay services HTTP server implementation.
Package main provides an example overlay services HTTP server implementation.
pkg
core/advertiser
Package advertiser provides interfaces and types for managing blockchain overlay advertisements.
Package advertiser provides interfaces and types for managing blockchain overlay advertisements.
core/basm
Package basm provides bounded BRC-136 hash calculations and structural validation of confirmed topic-admission claims.
Package basm provides bounded BRC-136 hash calculations and structural validation of confirmed topic-admission claims.
core/engine
Package engine provides the core overlay services engine implementation for managing and querying blockchain data.
Package engine provides the core overlay services engine implementation for managing and querying blockchain data.
core/gasp
Package gasp implements the Graph Aware Sync Protocol for synchronizing transaction graphs.
Package gasp implements the Graph Aware Sync Protocol for synchronizing transaction graphs.
server
Package server provides the HTTP server implementation for the overlay services API.
Package server provides the HTTP server implementation for the overlay services API.
server/config
Package config provides configuration management for the overlay-engine server.
Package config provides configuration management for the overlay-engine server.
server/config/exporters
Package exporters provides utilities for exporting configuration to various file formats.
Package exporters provides utilities for exporting configuration to various file formats.
server/config/loaders
Package loaders provides configuration loading utilities.
Package loaders provides configuration loading utilities.
server/internal/adapters
Package adapters provides adapter implementations for interfacing with external services and systems.
Package adapters provides adapter implementations for interfacing with external services and systems.
server/internal/app
Package app provides application-level services for the overlay server.
Package app provides application-level services for the overlay server.
server/internal/ports
Package ports defines the HTTP handlers and routing for the overlay services API.
Package ports defines the HTTP handlers and routing for the overlay services API.
server/internal/ports/decorators
Package decorators provides HTTP handler decorators for authentication and authorization.
Package decorators provides HTTP handler decorators for authentication and authorization.
server/internal/ports/middleware
Package middleware provides HTTP middleware components for request processing and server configuration.
Package middleware provides HTTP middleware components for request processing and server configuration.
server/internal/ports/openapi
Package openapi provides primitives to interact with the openapi HTTP API.
Package openapi provides primitives to interact with the openapi HTTP API.
server/internal/testabilities
Package testabilities provides mock implementations and test utilities for testing the overlay services server components.
Package testabilities provides mock implementations and test utilities for testing the overlay services server components.
storage/mongodb
Package mongodb provides an opt-in MongoDB engine.Storage adapter and the overlay-admission-v1 commit/ack capability.
Package mongodb provides an opt-in MongoDB engine.Storage adapter and the overlay-admission-v1 commit/ack capability.
storage/mongodb/internal/mongotest
Package mongotest starts disposable local MongoDB replica sets for opt-in integration tests.
Package mongotest starts disposable local MongoDB replica sets for opt-in integration tests.
topics/identity
Package identity implements the opt-in tm_identity application rules and ls_identity lookup service.
Package identity implements the opt-in tm_identity application rules and ls_identity lookup service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL