sl

package
v0.0.0-...-dd7c89d Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2025 License: MIT Imports: 16 Imported by: 1

README

sl

import "github.com/GeoNet/kit/seis/sl"

Overview

The sl module has been writen as a lightweight replacement for the C libslink library. It is aimed at clients that need to connect and decode data from a seedlink server.

The seedlink code is not a direct replacement for libslink. It can run in two modes, either as a raw connection to the client connection (Conn) which allows mechanisms to monitor or have a finer control of the SeedLink connection, or in the collection mode (SLink) where a connection is established and received miniseed blocks can be processed with a call back function. A context can be passed into the collection loop to allow interuption or as a shutdown mechanism. It is not passed to the underlying seedlink connection messaging which is managed via a deadline mechanism, e.g. the SetTimeout option.

An example Seedlink application can be as simple as:

 if err := sl.NewSLink().Collect(func(seq string, data []byte) (bool, error) {
	   //... process miniseed data

        return false, nil
 }); err != nil {
         log.Fatal(err)
 }

A state mechanism is available for the initial connection, although it is the clients responsibility to periodically maintain its content.

Index

Package files

conn.go doc.go info.go packet.go slink.go state.go stream.go

Constants

const (
    PacketSize = 8 + 512
)

type CollectFunc

type CollectFunc func(string, []byte) (bool, error)

CollectFunc is a function run on each returned seedlink packet. It should return a true value to stop collecting data without an error message. A non-nil returned error will also stop collection but with an assumed errored state.

type Conn

type Conn struct {
    net.Conn
    // contains filtered or unexported fields
}
func NewConn
func NewConn(service string, timeout time.Duration) (*Conn, error)

NewConn returns a new connection to the named seedlink server with a given command timeout. It is expected that the Close function be called when the connection is no longer required.

func (*Conn) Collect
func (c *Conn) Collect() (*Packet, error)

Collect returns a seedlink packet if available within the optional timout. Any error returned should be checked that it isn't a timeout, this should be handled as appropriate for the request.

func (*Conn) CommandCat
func (c *Conn) CommandCat() ([]byte, error)

CommandStationList sends a CAT command to the seedlink server.

func (*Conn) CommandClose
func (c *Conn) CommandClose() ([]byte, error)

CommandClose sends a BYE command to the seedlink server.

func (*Conn) CommandData
func (c *Conn) CommandData(sequence string, starttime time.Time) error

CommandData sends a DATA command to the seedlink server.

func (*Conn) CommandEnd
func (c *Conn) CommandEnd() error

CommandEnd sends an END command to the seedlink server.

func (*Conn) CommandHello
func (c *Conn) CommandHello() ([]byte, error)

CommandHello sends a HELLO command to the seedlink server.

func (*Conn) CommandId
func (c *Conn) CommandId() ([]byte, error)

CommandId sends an INFO ID command to the seedlink server.

func (*Conn) CommandSelect
func (c *Conn) CommandSelect(selection string) error

CommandSelect sends a SELECT command to the seedlink server.

func (*Conn) CommandStation
func (c *Conn) CommandStation(station, network string) error

CommandStation sends a STATION command to the seedlink server.

func (*Conn) CommandTime
func (c *Conn) CommandTime(starttime, endtime time.Time) error

CommandTime sends a TIME command to the seedlink server.

func (*Conn) GetInfo
func (c *Conn) GetInfo(level string) (*Info, error)

GetInfo requests the seedlink server return an INFO request for the given level. The results are returned as a decoded Info pointer, or an error otherwise.

func (*Conn) GetInfoLevel
func (c *Conn) GetInfoLevel(level string) ([]byte, error)

GetInfoLevel requests the seedlink server return an INFO request for the given level.

type Info

type Info struct {
    XMLName xml.Name `xml:"seedlink"`

    Software     string `xml:"software,attr"`
    Organization string `xml:"organization,attr"`
    Started      string `xml:"started,attr"`
    Capability   []struct {
        Name string `xml:"name,attr"`
    } `xml:"capability"`
    Station []struct {
        Name        string `xml:"name,attr"`
        Network     string `xml:"network,attr"`
        Description string `xml:"description,attr"`
        BeginSeq    string `xml:"begin_seq,attr"`
        EndSeq      string `xml:"end_seq,attr"`
        StreamCheck string `xml:"stream_check,attr"`
        Stream      []struct {
            Location  string `xml:"location,attr"`
            Seedname  string `xml:"seedname,attr"`
            Type      string `xml:"type,attr"`
            BeginTime string `xml:"begin_time,attr"`
            EndTime   string `xml:"end_time,attr"`
        } `xml:"stream"`
    } `xml:"station"`
}
func (*Info) Unmarshal
func (s *Info) Unmarshal(data []byte) error

type Packet

type Packet struct {
    SL   [2]byte   // ASCII String == "SL"
    Seq  [6]byte   // ASCII sequence number
    Data [512]byte // Fixed size payload
}
func NewPacket
func NewPacket(data []byte) (*Packet, error)

type PacketError

type PacketError struct {
    // contains filtered or unexported fields
}
func NewPacketError
func NewPacketError(message string) *PacketError
func (*PacketError) Error
func (e *PacketError) Error() string

type SLink struct {
    Server  string
    Timeout time.Duration

    NetTo     time.Duration
    KeepAlive time.Duration
    Strict    bool

    Start    time.Time
    End      time.Time
    Sequence int

    Streams   string
    Selectors string

    State []Station
}

SLink is a wrapper around an SLConn to provide handling of timeouts and keep alive messages.

func NewSLink(opts ...SLinkOpt) *SLink

NewSlink returns a SLink pointer for the given server, optional settings can be passed as SLinkOpt functions.

func (s *SLink) AddState(stations ...Station)

AddState appends the list of station state information.

func (s *SLink) Collect(fn CollectFunc) error

Collect calls CollectWithContext with a background Context and a handler function.

func (s *SLink) CollectWithContext(ctx context.Context, fn CollectFunc) error

CollectWithContext makes a connection to the seedlink server, recovers initial client information and the sets the connection into streaming mode. Recovered packets are passed to a given function to process, if this function returns a true value or a non-nil error value the collection will stop and the function will return. If a call returns with a timeout error a check is made whether a keepalive is needed or whether the function should return as no data has been received for an extended period of time. It is assumed the calling function will attempt a reconnection with an updated set of options, specifically any start or end time parameters. The Context parameter can be used to to cancel the data collection independent of the function as this may never be called if no appropriate has been received.

func (s *SLink) SetEnd(t time.Time)

SetEndTime sets the initial end time of the request.

func (s *SLink) SetKeepAlive(d time.Duration)

SetKeepAlive sets the time interval needed without any packets for a check message is sent.

func (s *SLink) SetNetTo(d time.Duration)

SetNetTo sets the overall timeout after which a reconnection is tried.

func (s *SLink) SetSelectors(selectors string)

SetSelectors sets the channel selectors used for seedlink connections.

func (s *SLink) SetSequence(sequence int)

SetSequence sets the start sequence for the initial request.

func (s *SLink) SetStart(t time.Time)

SetStartTime sets the initial starting time of the request.

func (s *SLink) SetState(stations ...Station)

SetState sets the default list of station state information.

func (s *SLink) SetStreams(streams string)

SetStreams sets the channel streams used for seedlink connections.

func (s *SLink) SetTimeout(d time.Duration)

SetTimeout sets the timeout value used for connection requests.

type SLinkOpt

type SLinkOpt func(*SLink)

SLinkOpt is a function for setting SLink internal parameters.

func SetEnd
func SetEnd(t time.Time) SLinkOpt

SetEndTime sets the end of the initial request from the seedlink server.

func SetKeepAlive
func SetKeepAlive(d time.Duration) SLinkOpt

SetKeepAlive sets the time to send an ID message to server if no packets have been received.

func SetNetTo
func SetNetTo(d time.Duration) SLinkOpt

SetNetTo sets the time to after which the connection is closed after no packets have been received.

func SetSelectors
func SetSelectors(selectors string) SLinkOpt

SetSelectors sets the default list of selectors to use for seedlink stream requests.

func SetSequence
func SetSequence(sequence int) SLinkOpt

SetSequence sets the start sequence for the initial request.

func SetServer
func SetServer(v string) SLinkOpt

SetServer sets the seedlink server in the form of "host<:port>".

func SetStart
func SetStart(t time.Time) SLinkOpt

SetStart sets the start of the initial request from the seedlink server.

func SetState
func SetState(stations ...Station) SLinkOpt

SetState sets the default list of station state information, only used during the initial connection.

func SetStreams
func SetStreams(streams string) SLinkOpt

SetStreams sets the list of stations and streams to from the seedlink server.

func SetStrict
func SetStrict(strict bool) SLinkOpt

SetStrict sets whether a package error should restart the collection system, rather than be skipped.

func SetTimeout
func SetTimeout(d time.Duration) SLinkOpt

SetTimeout sets the timeout for seedlink server commands and packet requests.

type State

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

State maintains the current state information for a seedlink connection.

func (*State) Add
func (s *State) Add(station Station)

Add inserts or updates the station collection details into the connection state.

func (*State) Find
func (s *State) Find(stn Station) *Station
func (*State) Marshal
func (s *State) Marshal() ([]byte, error)
func (*State) ReadFile
func (s *State) ReadFile(path string) error
func (*State) Stations
func (s *State) Stations() []Station

Stations returns a sorted slice of current station state information.

func (*State) Unmarshal
func (s *State) Unmarshal(data []byte) error
func (*State) WriteFile
func (s *State) WriteFile(path string) error

type Station

type Station struct {
    Network   string    `json:"network"`
    Station   string    `json:"station"`
    Sequence  int       `json:"sequence"`
    Timestamp time.Time `json:"timestamp"`
}

Station stores the latest state information for the given network and station combination.

func (Station) Key
func (s Station) Key() Station

Key returns a blank Station except for the Network and Station entries, this useful as a map key.

Generated by godoc2md

Documentation

Overview

The sl module has been writen as a lightweight replacement for the C libslink library. It is aimed at clients that need to connect and decode data from a seedlink server.

The seedlink code is not a direct replacement for libslink. It can run in two modes, either as a raw connection to the client connection (Conn) which allows mechanisms to monitor or have a finer control of the SeedLink connection, or in the collection mode (SLink) where a connection is established and received miniseed blocks can be processed with a call back function. A context can be passed into the collection loop to allow interuption or as a shutdown mechanism. It is not passed to the underlying seedlink connection messaging which is managed via a deadline mechanism, e.g. the `SetTimeout` option.

An example Seedlink application can be as simple as: 

 if err := sl.NewSLink().Collect(func(seq string, data []byte) (bool, error) {
	   //... process miniseed data

        return false, nil
 }); err != nil {
         log.Fatal(err)
 }

A state mechanism is available for the initial connection, although it is the clients responsibility to periodically maintain its content.

Index

Constants

View Source 
const (
	PacketSize = 8 + 512
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CollectFunc 

type CollectFunc func(string, []byte) (bool, error)

CollectFunc is a function run on each returned seedlink packet. It should return a true value to stop collecting data without an error message. A non-nil returned error will also stop collection but with an assumed errored state.

type Conn 

type Conn struct {
	net.Conn
	// contains filtered or unexported fields
}

func NewConn 

func NewConn(service string, timeout time.Duration) (*Conn, error)

NewConn returns a new connection to the named seedlink server with a given command timeout. It is expected that the Close function be called when the connection is no longer required.

func (*Conn) Collect 

func (c *Conn) Collect() (*Packet, error)

Collect returns a seedlink packet if available within the optional timout. Any error returned should be checked that it isn't a timeout, this should be handled as appropriate for the request.

func (*Conn) CommandCat 

func (c *Conn) CommandCat() ([]byte, error)

CommandStationList sends a CAT command to the seedlink server.

func (*Conn) CommandClose 

func (c *Conn) CommandClose() ([]byte, error)

CommandClose sends a BYE command to the seedlink server.

func (*Conn) CommandData 

func (c *Conn) CommandData(sequence string, starttime time.Time) error

CommandData sends a DATA command to the seedlink server.

func (*Conn) CommandEnd 

func (c *Conn) CommandEnd() error

CommandEnd sends an END command to the seedlink server.

func (*Conn) CommandHello 

func (c *Conn) CommandHello() ([]byte, error)

CommandHello sends a HELLO command to the seedlink server.

func (*Conn) CommandId 

func (c *Conn) CommandId() ([]byte, error)

CommandId sends an INFO ID command to the seedlink server.

func (*Conn) CommandSelect 

func (c *Conn) CommandSelect(selection string) error

CommandSelect sends a SELECT command to the seedlink server.

func (*Conn) CommandStation 

func (c *Conn) CommandStation(station, network string) error

CommandStation sends a STATION command to the seedlink server.

func (*Conn) CommandTime 

func (c *Conn) CommandTime(starttime, endtime time.Time) error

CommandTime sends a TIME command to the seedlink server.

func (*Conn) GetInfo 

func (c *Conn) GetInfo(level string) (*Info, error)

GetInfo requests the seedlink server return an INFO request for the given level. The results are returned as a decoded Info pointer, or an error otherwise.

func (*Conn) GetInfoLevel 

func (c *Conn) GetInfoLevel(level string) ([]byte, error)

GetInfoLevel requests the seedlink server return an INFO request for the given level.

type Info 

type Info struct {
	XMLName xml.Name `xml:"seedlink"`

	Software     string `xml:"software,attr"`
	Organization string `xml:"organization,attr"`
	Started      string `xml:"started,attr"`
	Capability   []struct {
		Name string `xml:"name,attr"`
	} `xml:"capability"`
	Station []struct {
		Name        string `xml:"name,attr"`
		Network     string `xml:"network,attr"`
		Description string `xml:"description,attr"`
		BeginSeq    string `xml:"begin_seq,attr"`
		EndSeq      string `xml:"end_seq,attr"`
		StreamCheck string `xml:"stream_check,attr"`
		Stream      []struct {
			Location  string `xml:"location,attr"`
			Seedname  string `xml:"seedname,attr"`
			Type      string `xml:"type,attr"`
			BeginTime string `xml:"begin_time,attr"`
			EndTime   string `xml:"end_time,attr"`
		} `xml:"stream"`
	} `xml:"station"`
}

func (*Info) Unmarshal 

func (s *Info) Unmarshal(data []byte) error

type Packet 

type Packet struct {
	SL   [2]byte   // ASCII String == "SL"
	Seq  [6]byte   // ASCII sequence number
	Data [512]byte // Fixed size payload
}

func NewPacket 

func NewPacket(data []byte) (*Packet, error)

type PacketError 

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

func NewPacketError 

func NewPacketError(message string) *PacketError

func (*PacketError) Error 

func (e *PacketError) Error() string
type SLink struct {
	Server  string
	Timeout time.Duration

	NetTo     time.Duration
	KeepAlive time.Duration
	Strict    bool

	Start    time.Time
	End      time.Time
	Sequence int

	Streams   string
	Selectors string

	State []Station
}

SLink is a wrapper around an SLConn to provide handling of timeouts and keep alive messages. 

func NewSLink(opts ...SLinkOpt) *SLink

NewSlink returns a SLink pointer for the given server, optional settings can be passed as SLinkOpt functions.

func (*SLink) AddState 

func (s *SLink) AddState(stations ...Station)

AddState appends the list of station state information.

func (*SLink) Collect 

func (s *SLink) Collect(fn CollectFunc) error

Collect calls CollectWithContext with a background Context and a handler function.

func (*SLink) CollectWithContext 

func (s *SLink) CollectWithContext(ctx context.Context, fn CollectFunc) error

CollectWithContext makes a connection to the seedlink server, recovers initial client information and the sets the connection into streaming mode. Recovered packets are passed to a given function to process, if this function returns a true value or a non-nil error value the collection will stop and the function will return. If a call returns with a timeout error a check is made whether a keepalive is needed or whether the function should return as no data has been received for an extended period of time. It is assumed the calling function will attempt a reconnection with an updated set of options, specifically any start or end time parameters. The Context parameter can be used to to cancel the data collection independent of the function as this may never be called if no appropriate has been received.

func (*SLink) SetEnd 

func (s *SLink) SetEnd(t time.Time)

SetEndTime sets the initial end time of the request.

func (*SLink) SetKeepAlive 

func (s *SLink) SetKeepAlive(d time.Duration)

SetKeepAlive sets the time interval needed without any packets for a check message is sent.

func (*SLink) SetNetTo 

func (s *SLink) SetNetTo(d time.Duration)

SetNetTo sets the overall timeout after which a reconnection is tried.

func (*SLink) SetSelectors 

func (s *SLink) SetSelectors(selectors string)

SetSelectors sets the channel selectors used for seedlink connections.

func (*SLink) SetSequence 

func (s *SLink) SetSequence(sequence int)

SetSequence sets the start sequence for the initial request.

func (*SLink) SetStart 

func (s *SLink) SetStart(t time.Time)

SetStartTime sets the initial starting time of the request.

func (*SLink) SetState 

func (s *SLink) SetState(stations ...Station)

SetState sets the default list of station state information.

func (*SLink) SetStreams 

func (s *SLink) SetStreams(streams string)

SetStreams sets the channel streams used for seedlink connections.

func (*SLink) SetTimeout 

func (s *SLink) SetTimeout(d time.Duration)

SetTimeout sets the timeout value used for connection requests.

type SLinkOpt 

type SLinkOpt func(*SLink)

SLinkOpt is a function for setting SLink internal parameters.

func SetEnd 

func SetEnd(t time.Time) SLinkOpt

SetEndTime sets the end of the initial request from the seedlink server.

func SetKeepAlive 

func SetKeepAlive(d time.Duration) SLinkOpt

SetKeepAlive sets the time to send an ID message to server if no packets have been received.

func SetNetTo 

func SetNetTo(d time.Duration) SLinkOpt

SetNetTo sets the time to after which the connection is closed after no packets have been received.

func SetSelectors 

func SetSelectors(selectors string) SLinkOpt

SetSelectors sets the default list of selectors to use for seedlink stream requests.

func SetSequence 

func SetSequence(sequence int) SLinkOpt

SetSequence sets the start sequence for the initial request.

func SetServer 

func SetServer(v string) SLinkOpt

SetServer sets the seedlink server in the form of "host<:port>".

func SetStart 

func SetStart(t time.Time) SLinkOpt

SetStart sets the start of the initial request from the seedlink server.

func SetState 

func SetState(stations ...Station) SLinkOpt

SetState sets the default list of station state information, only used during the initial connection.

func SetStreams 

func SetStreams(streams string) SLinkOpt

SetStreams sets the list of stations and streams to from the seedlink server.

func SetStrict 

func SetStrict(strict bool) SLinkOpt

SetStrict sets whether a package error should restart the collection system, rather than be skipped.

func SetTimeout 

func SetTimeout(d time.Duration) SLinkOpt

SetTimeout sets the timeout for seedlink server commands and packet requests.

type State 

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

State maintains the current state information for a seedlink connection.

func (*State) Add 

func (s *State) Add(station Station)

Add inserts or updates the station collection details into the connection state.

func (*State) Find 

func (s *State) Find(stn Station) *Station

func (*State) Marshal 

func (s *State) Marshal() ([]byte, error)

func (*State) ReadFile 

func (s *State) ReadFile(path string) error

func (*State) Stations 

func (s *State) Stations() []Station

Stations returns a sorted slice of current station state information.

func (*State) Unmarshal 

func (s *State) Unmarshal(data []byte) error

func (*State) WriteFile 

func (s *State) WriteFile(path string) error

type Station 

type Station struct {
	Network   string    `json:"network"`
	Station   string    `json:"station"`
	Sequence  int       `json:"sequence"`
	Timestamp time.Time `json:"timestamp"`
}

Station stores the latest state information for the given network and station combination.

func (Station) Key 

func (s Station) Key() Station

Key returns a blank Station except for the Network and Station entries, this useful as a map key.

Source Files

View all Source files

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.