tseventserver

package module
v1.2.3 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

README

tseventserver

PkgGoDev GitHub go.mod Go version

Go Report Card CodeFactor OSS Lifecycle Libraries.io dependency status for GitHub repo

GitHub release (latest by date) GitHub last commit GitHub commit activity GitHub code size in bytes GitHub Top Language GitHub

tseventserver is a Go package for ingesting and querying economic calendar events.
It provides an HTTP API backed by Google Cloud Firestore, with a token‑authenticated
retrieval endpoint.

Features

  • Ingestion – POST /events/ingest accepts an array of economic events (JSON) and
    upserts them into Firestore.
  • Retrieval – GET /events/retrieve?from=…&to=… returns events within a time range,
    secured by a bearer token.
  • Google Cloud Firestore – production‑ready storage with automatic backend
    detection via GOOGLE_CLOUD_PROJECT and FIRESTORE_EMULATOR_HOST.
  • Tested – unit tests with high code coverage

Getting Started

Prerequisites
  • Go 1.26+
  • A Firestore database (or the Firestore emulator for local development)
  • Docker (for running the emulator via script)
  • (Optional) gcloud CLI for deployment to Cloud Run
Local Development with the Firestore Emulator

Option A – One‑command runner (recommended)

The run_local.sh script starts the Firestore emulator (via Docker), launches the server, and runs a quick smoke test — all in one terminal:

./run_local.sh

Press Ctrl+C to stop everything and clean up.

Option B – Manual steps

  1. Start the Firestore emulator:

    docker run -d --name firestore-emulator -p 8081:8081 \
  google/cloud-sdk:emulators \
  gcloud beta emulators firestore start --host-port=0.0.0.0:8081

  2. Set the required environment variables and run the server:

    export FIRESTORE_EMULATOR_HOST=localhost:8081
export GOOGLE_CLOUD_PROJECT=demo-project
go run ./cmd/main.go

  3. In another terminal, run the smoke test against the local server:

    ./smoke_test.sh http://localhost:8080

Note: The emulator does not persist data between restarts.

Build & Run the Binary
go build -o eventserver ./cmd/main.go
API_TOKEN=swordfish ./eventserver

The server listens on port 8080 by default (PORT env var overrides it).

Running Tests

The unit tests (nil-pointer checks, event formatting) run without any setup:

go test -v ./...

The Firestore integration tests (TestFirestoreStoreAndGetByPeriod and TestFirestoreGetByPeriodEmpty) require a running emulator and will fail with clear instructions if one is not found. Use the convenience script to run them:

./test_firestore.sh

This starts a Firestore emulator container, runs all tests (including integration), and cleans up afterwards. If you prefer to run the emulator manually:

docker run -d --name firestore-emulator -p 8081:8081 \
    google/cloud-sdk:emulators \
    gcloud beta emulators firestore start --host-port=0.0.0.0:8081

export FIRESTORE_EMULATOR_HOST=localhost:8081
go test -v ./...

docker rm -f firestore-emulator

API Reference

Authentication

Every request requires the Authorization header:

Authorization: Bearer <API_TOKEN>

The token is set via the API_TOKEN environment variable.
If omitted, the default token is swordfish (local development only).

Endpoints
POST /events/ingest

Ingest one or more economic events. Existing events (same time, country, name) are updated automatically.

Request body – JSON array of event objects:

[
  {
    "name": "US Core Inflation Rate",
    "time": "2026-05-15T12:30:00Z",
    "country": "US",
    "actual": 3.1,
    "estimate": 3.2,
    "previous": 3.3,
    "unit": "%",
    "impact": 3,
    "source": "US Bureau of Labor Statistics"
  }
]

Responses

Status Meaning
200 Events ingested successfully
400 Invalid JSON body
401 Missing or invalid token
500 Storage error
GET /events/retrieve

Retrieve events within a time window.

Query parameters

Param Required Format Example
from yes* RFC 3339 (UTC) 2026-05-01T00:00:00Z
to yes* RFC 3339 (UTC) 2026-05-31T23:59:59Z

* When from and to are omitted the endpoint returns events for the current UTC day.

Example

curl -H "Authorization: Bearer swordfish" \
  "http://localhost:8080/events/retrieve?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z"

Responses

Status Meaning
200 JSON array of events (may be empty)
400 Invalid timestamp format
401 Missing or invalid token
500 Storage error

Deployment to Cloud Run

Prerequisites
  • A Firestore database named eventdb must exist in your Google Cloud project.
  • The Cloud Run service account must have the Datastore User role to read and write to Firestore.
Deploy

The included deploy.sh script handles the complete deployment. It reads configuration from environment variables (with sensible defaults for some).

Required variables

Variable Purpose
PROJECT_ID Your Google Cloud project ID
SERVICE_NAME Cloud Run service name (e.g., eventserver)
API_BEARER_KEY The token used to secure your API (set via API_TOKEN on the server)
REGION (optional) Deployment region, defaults to us-east4

Example

export PROJECT_ID=thorsphere-trading-stg
export SERVICE_NAME=eventserver
export API_BEARER_KEY=your-super-secret-token
./deploy.sh

The script sets GOOGLE_CLOUD_PROJECT and API_TOKEN automatically, ensures the eventdb Firestore database exists, and prints the service URL at the end.

Automated deployments are handled by the GitHub Actions workflow (.github/workflows/deploy.yml), which uses the same deploy.sh script.

Once deployed, verify with the smoke test:

./smoke_test.sh https://your-service.run.app

SQLite Support (Archived)

The SQLite‑backed EventRepository was used for prototyping and local development before the project moved to a Firestore‑only backend.
It has been removed from the main branch to keep the binary lean.

If you need the SQLite implementation for reference or local testing, it is available in two places:

  • GitHub Gist — SQLite EventRepository for tsecon
    Contains repository_sqlite.go and repository_sqlite_test.go with the full implementation and test suite.

  • Git tag v1.0.0 — The last release that includes the complete SQLite backend alongside the Firestore implementation.

License

GNU Affero General Public License v3.0 – see LICENSE for details.

Documentation

Overview

Package tseventserver provides the core types and interfaces for economic calendar events, including an HTTP‑based ingestion and retrieval server, and pluggable storage backends (SQLite and Google Cloud Firestore).

Key types

  • [Event] represents a single economic release (e.g., GDP, CPI) with its actual, estimate, previous, and impact fields.
  • EventRepository is the storage interface implemented by [SQLiteEventRepository] and FirestoreEventRepository.
  • EventServer exposes authenticated HTTP endpoints: /events/ingest (POST) and /events/retrieve (GET).

Typical usage

Create a repository, then start the server: 

repo, err := tseventserver.NewSQLiteEventRepository("events.db")
// ... error handling ...
defer repo.Close()
api := tseventserver.NewEventServer(repo, "your-api-token")
http.ListenAndServe(":8080", api)

Copyright (c) 2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Copyright (c) 2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Copyright (c) 2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type EventRepository 

type EventRepository interface {
	Store(ctx context.Context, event *tstrading.Event) error                              // Store saves a new economic event to the repository. If it already exists, it should update the existing record.
	GetByPeriod(ctx context.Context, period *tstrading.Period) ([]tstrading.Event, error) // GetByPeriod retrieves economic events that occurred within a specified time period.
	Close() error                                                                         // Close releases any resources held by the repository, such as database connections.
}

EventRepository defines the interface for managing economic events in a storage system.

type EventServer 

type EventServer struct {
	// contains filtered or unexported fields
}

EventServer is a struct that represents the event server responsible for handling event ingestion.

func NewEventServer 

func NewEventServer(repo EventRepository, tok string) *EventServer

NewEventServer creates a new instance of EventServer with the provided EventRepository.

func (*EventServer) ServeHTTP 

func (s *EventServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes EventServer implement the http.Handler interface, allowing it to easily route incoming requests to its internal multiplexer. This handles HTTP requests natively and is especially useful for testing.

type FirestoreEventRepository 

type FirestoreEventRepository struct {
	// contains filtered or unexported fields
}

FirestoreEventRepository is an implementation of the EventRepository interface that uses Google Cloud Firestore as the storage backend.

func NewFirestoreEventRepository 

func NewFirestoreEventRepository(ctx context.Context, projectID string) (*FirestoreEventRepository, error)

NewFirestoreEventRepository creates a new instance of FirestoreEventRepository with the provided Google Cloud project ID.

func (*FirestoreEventRepository) Close 

func (r *FirestoreEventRepository) Close() error

Close closes the connection to the Firestore database and releases any associated resources.

func (*FirestoreEventRepository) GetByPeriod 

func (r *FirestoreEventRepository) GetByPeriod(ctx context.Context, period *tstrading.Period) ([]tstrading.Event, error)

GetByPeriod retrieves economic events that occurred within a specified time period.

func (*FirestoreEventRepository) Store 

func (r *FirestoreEventRepository) Store(ctx context.Context, event *tstrading.Event) error

Store saves a new economic event to the FirestoreEventRepository. It generates a deterministic document ID to seamlessly perform an upsert.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.