winsgo

README

winsgo

winsgo is a pure-Go implementation of the Winston Wave Server (WWS) protocol. It supports Winston protocol version 3 and separates protocol handling from waveform storage by exposing a pluggable Provider for channel metadata and a Consumer for waveform data.

Preview

Features

• Winston Wave Server protocol v3 support
• MENU, GETCHANNELS, GETMETADATA, GETWAVERAW, GETSCN/GETSCNL, GETSCNRAW/GETSCNLRAW, GETSCNLHELIRAW, GETSCNLRSAMRAW, and STATUS commands
• Pure Go implementation with no external dependencies beyond the standard library
• Pluggable Provider and Consumer interfaces for custom metadata and waveform sources
• Optional hooks for connection, command, data, error, and close events
• Built-in support for compressed GETWAVERAW and Swarm-compatible product payloads

Installation

Install the package for use in your Go module:

$ go get github.com/bclswl0827/winsgo

Or install the command directly if you expose a main package from the repo:

$ go install github.com/bclswl0827/winsgo@latest

Quick Usage

Implement a Provider for channel metadata and a Consumer for waveform data, then start the server with winsgo.New.

package main

import (
    "context"
    "log"
    "os"
    "os/signal"
    "syscall"

    "github.com/bclswl0827/winsgo"
)

func main() {
    server := winsgo.New(&provider{}, &consumer{}, &hooks{})
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()

    log.Println("starting Winston server on 0.0.0.0:16022")
    if err := server.Start(ctx, "0.0.0.0", 16022); err != nil {
        log.Fatal(err)
    }
}

Example implementations are available in the example/ directory.

Project layout

• go.mod — Go module definition
• server.go — core server loop, connection handling, and command parsing
• protocol.go — Winston command handling and response generation
• types.go — protocol data types, provider/consumer interfaces, and hooks
• waveform.go — waveform encoding and ZiLib compression utilities
• example/ — sample provider, consumer, hooks, and server launcher
• preview/ — project preview assets

Contributing

Contributions, issues, and feature requests are welcome. Please open an issue or pull request on the upstream repository.

License

This project is licensed under the MIT License.

Documentation

Index

• Constants
• Variables
• func EncodeWaveform(wave Waveform) ([]byte, error)
• func J2KSeconds(t time.Time) float64
• func TimeFromJ2K(seconds float64) time.Time
• type Channel
• type Client
  • func (c *Client) RemoteAddr() net.Addr
• type Command
• type Consumer
• type ErrorHooks
• type Hooks
• type Instrument
• type Product
• type ProductConsumer
• type ProductRequest
• type Provider
• type SCNL
  • func (s SCNL) Code() string
  • func (s SCNL) String() string
• type Server
  • func New(provider Provider, consumer Consumer, hooks Hooks) *Server
  • func (s *Server) Serve(ctx context.Context, listener net.Listener) error
  • func (s *Server) Start(ctx context.Context, host string, port int) error
• type TraceBuf
• type TraceBufConsumer
• type Waveform
• type WaveformHandler
• type WaveformRequest

Constants

const J2KEpoch = 946728000000

epoch used by Winston: 2000-01-01 12:00:00 UTC.

Variables

var ErrNoData = errors.New("winsgo: no data")

Functions

func EncodeWaveform

func EncodeWaveform(wave Waveform) ([]byte, error)

EncodeWaveform produces the big-endian binary representation used in a Winston GETWAVERAW response and by volcano-core's Wave.toBinary().

func J2KSeconds

func J2KSeconds(t time.Time) float64

J2KSeconds converts a time to decimal seconds since J2KEpoch.

func TimeFromJ2K

func TimeFromJ2K(seconds float64) time.Time

TimeFromJ2K converts decimal J2K seconds to a UTC time.

Types

type Channel

type Channel struct {
	ID         int
	SCNL       SCNL
	StartTime  time.Time
	EndTime    time.Time
	Instrument Instrument
	Alias      string
	Unit       string
	LinearA    float64
	LinearB    float64
	Groups     []string
	Metadata   map[string]string
}

Channel describes one channel advertised by MENU and GETCHANNELS.

type Client

type Client struct {
	Conn net.Conn
}

Client is the connection information exposed to Hooks.

func (*Client) RemoteAddr

func (c *Client) RemoteAddr() net.Addr

type Command

type Command struct {
	Name string
	ID   string
	Args []string
	Raw  string
}

Command is a parsed Winston request.

type Consumer

type Consumer interface {
	Consume(context.Context, WaveformRequest, WaveformHandler) error
}

Consumer fulfills waveform requests. It may return ErrNoData without invoking the handler when no waveform overlaps the requested interval.

type ErrorHooks

type ErrorHooks interface {
	OnError(*Client, error)
}

ErrorHooks may be implemented in addition to Hooks to observe the reason a connection handler is closing.

type Hooks

type Hooks interface {
	OnConnection(*Client)
	OnCommand(*Client, Command)
	OnData(*Client, []byte)
	OnClose(*Client)
}

Hooks observes server activity. Hook methods must return quickly and must not retain or modify byte slices passed to OnData.

type Instrument

type Instrument struct {
	ID          int
	Name        string
	Description string
	Longitude   float64
	Latitude    float64
	Height      float64
	TimeZone    string
	Metadata    map[string]string
}

Instrument contains the station metadata returned by GETMETADATA.

type Product

type Product int

Product identifies an optional Winston binary derived-data response.

const (
	HelicorderProduct Product = iota + 1
	RSAMProduct
)

type ProductConsumer

type ProductConsumer interface {
	ConsumeProduct(context.Context, ProductRequest, func([]byte) error) error
}

ProductConsumer optionally overrides server-side derivation of Winston binary products. The callback accepts the uncompressed, Winston-compatible representation.

type ProductRequest

type ProductRequest struct {
	WaveformRequest
	Product Product
	Period  int
}

ProductRequest describes GETSCNLHELIRAW and GETSCNLRSAMRAW requests.

type Provider

type Provider interface {
	Channels(context.Context) ([]Channel, error)
}

Provider supplies the channel catalog. It is deliberately separate from the waveform Consumer so metadata and waveform data may come from different systems.

type SCNL

type SCNL struct {
	Station  string
	Channel  string
	Network  string
	Location string
}

SCNL identifies a seismic channel by station, channel, network, and location.

func (SCNL) Code

func (s SCNL) Code() string

Code returns Winston's dollar-separated channel code.

func (SCNL) String

func (s SCNL) String() string

String returns the space-separated SCNL representation used on the wire.

type Server

type Server struct {
	Provider Provider
	Consumer Consumer

	MaxCommandSize int
	// DisableHelicorder disables the GETSCNLHELIRAW command. Clients that send
	// GETSCNLHELIRAW will receive an unsupported-command error.
	DisableHelicorder bool
	// contains filtered or unexported fields
}

Server implements Winston Wave Server protocol version 3.

func New

func New(provider Provider, consumer Consumer, hooks Hooks) *Server

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, listener net.Listener) error

Serve accepts connections from listener until ctx is canceled. It closes the listener and all active clients before returning.

func (*Server) Start

func (s *Server) Start(ctx context.Context, host string, port int) error

Start listens at host:port and serves until ctx is canceled.

type TraceBuf

type TraceBuf struct {
	StartTime time.Time
	EndTime   time.Time
	DataType  string
	Bytes     []byte
}

TraceBuf is an already encoded Earthworm tracebuf or tracebuf2 record.

type TraceBufConsumer

type TraceBufConsumer interface {
	ConsumeTraceBuf(context.Context, WaveformRequest, func(TraceBuf) error) error
}

TraceBufConsumer optionally enables GETSCNRAW and GETSCNLRAW. Raw records are not synthesized from Waveform because Winston promises to return their original form.

type Waveform

type Waveform struct {
	StartTime          time.Time
	SampleRate         float64
	RegistrationOffset float64
	Samples            []int32
	// DataType defaults to "s4", the Earthworm signed 32-bit sample type.
	DataType string
}

Waveform is Winston's regularly sampled, signed 32-bit waveform type.

type WaveformHandler

type WaveformHandler func(Waveform) error

WaveformHandler delivers a waveform to the server. A Consumer must call the handler at most once and must not call it after Consume returns.

type WaveformRequest

type WaveformRequest struct {
	ID        string
	Channel   SCNL
	StartTime time.Time
	EndTime   time.Time
}

WaveformRequest is the normalized request passed to a Consumer. StartTime and EndTime are always UTC instants, regardless of the protocol command's time base.