var (
	ErrClosed         // closed by the application
	ErrNotConnected   // client has no connection
	ErrConnectFailed  // Connect/Dial failed; wraps the cause
	ErrNotStarted     // data transfer stopped
	ErrConnectionLost // peer closed or transport failed
	ErrTimeout        // t1 expired; connection closed
	ErrProtocol       // peer violated the protocol; connection closed
	ErrBusy           // identical request or conflicting procedure pending
	ErrInHandler      // client request method called from inside a handler
	ErrInvalidOption  // option value a client or server cannot be built with
)

type NegativeError struct{ ASDU *asdu.ASDU }
func (e *NegativeError) Error() string
func (e *NegativeError) Cause() asdu.Cause

type State uint8
const (
	StateDisconnected State = iota // no transport connection
	StateConnecting                // client is (re)establishing the connection
	StateStopped                   // connected, data transfer stopped (STOPDT)
	StateStarted                   // connected, data transfer started (STARTDT)
)
func (s State) String() string

type Logger interface {
	Debugf(format string, args ...any)
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
	Errorf(format string, args ...any)
}
func NewSlogLogger(h slog.Handler) Logger
func NewStdLogger(l *log.Logger) Logger
func NopLogger() Logger

type Metrics interface {
	OnConnect(remote net.Addr)
	OnDisconnect(remote net.Addr, err error)
	OnFrameSent(remote net.Addr, f apci.Frame, size int)
	OnFrameReceived(remote net.Addr, f apci.Frame, size int)
	OnDecodeError(remote net.Addr, err error)
}
type NopMetrics struct{} // embed to implement a subset

// Optional extensions, detected on the value given to WithMetrics.
type RequestMetrics interface { // client
	OnRequest(remote net.Addr, t asdu.TypeID, ca asdu.CommonAddr)
	OnRequestDone(remote net.Addr, t asdu.TypeID, ca asdu.CommonAddr, duration time.Duration, err error)
	OnRetry(remote net.Addr, t asdu.TypeID, ca asdu.CommonAddr, attempt int, err error)
}
type HandlerMetrics interface { // server
	OnHandled(remote net.Addr, t asdu.TypeID, cause asdu.Cause, duration time.Duration)
}

// Optional extensions of Logger; NewSlogLogger returns both.
type FieldLogger interface {
	Logger
	With(keysAndValues ...any) FieldLogger
	DebugKV(msg string, keysAndValues ...any)
	InfoKV(msg string, keysAndValues ...any)
	WarnKV(msg string, keysAndValues ...any)
	ErrorKV(msg string, keysAndValues ...any)
}
type ContextLogger interface {
	Logger
	DebugContext(ctx context.Context, msg string, keysAndValues ...any)
	InfoContext(ctx context.Context, msg string, keysAndValues ...any)
	WarnContext(ctx context.Context, msg string, keysAndValues ...any)
	ErrorContext(ctx context.Context, msg string, keysAndValues ...any)
}
func NewSlogFieldLogger(h slog.Handler) FieldLogger

func New(addr string, opts ...Option) (*Client, error)
func Dial(ctx context.Context, addr string, opts ...Option) (*Client, error)

func (c *Client) Connect(ctx context.Context) error
func (c *Client) Close() error
func (c *Client) State() iec104.State
func (c *Client) Addr() string

type Handler interface{ HandleASDU(a *asdu.ASDU) }
type HandlerFunc func(a *asdu.ASDU)

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

type Reconnect struct{ MinDelay, MaxDelay time.Duration }

type Retry struct {
	Attempts   int           // total attempts, default 3
	Backoff    time.Duration // before the second attempt, doubling; default 500ms
	MaxBackoff time.Duration // default 10s
}

func (c *Client) StartDT(ctx context.Context) error  // STARTDT act → con
func (c *Client) StopDT(ctx context.Context) error   // STOPDT act → con
func (c *Client) TestLink(ctx context.Context) error // TESTFR act → con

func (c *Client) Interrogate(ctx context.Context, ca asdu.CommonAddr, qoi asdu.QOI) ([]*asdu.ASDU, error)
func (c *Client) CounterInterrogate(ctx context.Context, ca asdu.CommonAddr, request, freeze uint8) ([]*asdu.ASDU, error)
func (c *Client) Read(ctx context.Context, ca asdu.CommonAddr, ioa asdu.IOA) (*asdu.ASDU, error)
func (c *Client) ClockSync(ctx context.Context, ca asdu.CommonAddr, t time.Time) error
func (c *Client) Command(ctx context.Context, ca asdu.CommonAddr, obj asdu.InformationObject) error
func (c *Client) Deactivate(ctx context.Context, ca asdu.CommonAddr, obj asdu.InformationObject) error
func (c *Client) TestCommand(ctx context.Context, ca asdu.CommonAddr) error
func (c *Client) ResetProcess(ctx context.Context, ca asdu.CommonAddr, qualifier uint8) error
func (c *Client) GetFile(ctx context.Context, ca asdu.CommonAddr, ioa asdu.IOA, name uint16) ([]byte, error)
func (c *Client) PutFile(ctx context.Context, ca asdu.CommonAddr, ioa asdu.IOA, name uint16, sections ...[]byte) error
func (c *Client) ListFiles(ctx context.Context, ca asdu.CommonAddr, ioa asdu.IOA) ([]asdu.FileDirectoryEntry, error)

func (c *Client) Send(ctx context.Context, a *asdu.ASDU) error

func NewGroup(addrs []string, opts ...Option) (*Group, error)

func (g *Group) Connect(ctx context.Context) error
func (g *Group) Close() error
func (g *Group) Active() *Client   // nil when no connection is started
func (g *Group) Clients() []*Client
func (g *Group) Switchover(ctx context.Context) error

// On the active connection; ErrNotConnected when there is none:
func (g *Group) Interrogate(...)        func (g *Group) CounterInterrogate(...)
func (g *Group) Read(...)               func (g *Group) ClockSync(...)
func (g *Group) Command(...)            func (g *Group) Deactivate(...)
func (g *Group) TestCommand(...)        func (g *Group) ResetProcess(...)
func (g *Group) GetFile(...)            func (g *Group) PutFile(...)
func (g *Group) ListFiles(...)          func (g *Group) Send(...)

func New(h Handler, opts ...Option) (*Server, error)

func (s *Server) ListenAndServe(addr string) error
func (s *Server) Serve(ln net.Listener) error
func (s *Server) Close() error
func (s *Server) Addr() net.Addr
func (s *Server) Sessions() []*Session
func (s *Server) Broadcast(ctx context.Context, a *asdu.ASDU) (int, error)
func (s *Server) Enqueue(a *asdu.ASDU) error
func (s *Server) Pending(group string) int
func (s *Server) Dropped(group string) uint64

var ErrServerClosed error

type Handler interface{ HandleASDU(s *Session, a *asdu.ASDU) }
type HandlerFunc func(s *Session, a *asdu.ASDU)

type Mux struct{ /* zero value is ready */ }
func NewMux() *Mux
func (m *Mux) Handle(h Handler, types ...asdu.TypeID)
func (m *Mux) HandleFunc(t asdu.TypeID, f func(s *Session, req *asdu.ASDU))
func (m *Mux) HandleASDU(s *Session, a *asdu.ASDU)

var ProcessCommands []asdu.TypeID // types 45..51 and 58..64

type File struct{ Sections [][]byte }
func NewFile(data []byte, sectionSize int) File
func (f File) Len() int

type FileSource interface {
    OpenFile(s *Session, ca asdu.CommonAddr, ioa asdu.IOA, name uint16) (File, bool)
}
type FileSourceFunc func(s *Session, ca asdu.CommonAddr, ioa asdu.IOA, name uint16) (File, bool)

type FileSink interface {
    AcceptFile(s *Session, ca asdu.CommonAddr, ioa asdu.IOA, name uint16, length int) bool
    StoreFile(s *Session, ca asdu.CommonAddr, ioa asdu.IOA, name uint16, file File) error
}

type FileServer struct {
    Sink      FileSink
    Directory func(s *Session, ca asdu.CommonAddr, ioa asdu.IOA) []asdu.FileDirectoryEntry
    OnDone    func(s *Session, ca asdu.CommonAddr, ioa asdu.IOA, name uint16, err error)
}
func NewFileServer(source FileSource) *FileServer
func (f *FileServer) HandleASDU(s *Session, a *asdu.ASDU)

var FileTypes []asdu.TypeID // F_SC, F_AF, F_FR, F_SR, F_SG, F_LS
var ErrFileNotAcknowledged error

mux.Handle(server.NewFileServer(source), server.FileTypes...)

type RedundancyGroup struct {
	Name  string
	Allow []string // IP addresses or prefixes; empty: any client not claimed by an earlier group
}

func (s *Session) Group() string            // redundancy group
func (s *Session) ID() uint64
func (s *Session) RemoteAddr() net.Addr
func (s *Session) LocalAddr() net.Addr
func (s *Session) Conn() net.Conn           // e.g. to read the TLS peer certificate
func (s *Session) Context() context.Context // cancelled when the session ends
func (s *Session) Started() bool
func (s *Session) Err() error
func (s *Session) Close() error

func (s *Session) Send(ctx context.Context, a *asdu.ASDU) error
func (s *Session) Reply(req *asdu.ASDU, cause asdu.Cause, negative bool) error
func (s *Session) Confirm(req *asdu.ASDU) error   // activation/deactivation confirmation
func (s *Session) Negative(req *asdu.ASDU) error  // the same with P/N = 1
func (s *Session) Terminate(req *asdu.ASDU) error // activation termination
func (s *Session) Reject(req *asdu.ASDU, cause asdu.Cause) error // causes 44..47 with P/N = 1

type ASDU struct {
	Type       TypeID
	Sequence   bool   // SQ: one address, consecutive elements
	Cause      Cause
	Negative   bool   // P/N
	Test       bool   // T
	Originator uint8
	CommonAddr CommonAddr
	Objects    []InformationObject
	Raw        []byte // payload of a type without object model
	RawCount   int    // object count announced for Raw
}

func New(cause Cause, ca CommonAddr, objs ...InformationObject) *ASDU
func Decode(b []byte, p Params) (*ASDU, error)
func (a *ASDU) Encode(p Params) ([]byte, error)
func (a *ASDU) AppendEncode(b []byte, p Params) ([]byte, error)
func (a *ASDU) Reply(cause Cause, negative bool) *ASDU
func (a *ASDU) First() InformationObject
func (a *ASDU) Len() int
func (a *ASDU) String() string

func TypeOf(obj InformationObject) TypeID

type Params struct {
	CauseSize      int            // 1 or 2
	CommonAddrSize int            // 1 or 2
	IOASize        int            // 1, 2 or 3
	MaxSize        int            // 0 means 249
	Location       *time.Location // zone of time tags; nil means UTC
}
var IEC104 = Params{CauseSize: 2, CommonAddrSize: 2, IOASize: 3, MaxSize: 249}

func (p Params) Validate() error
func (p Params) In(loc *time.Location) Params
func (p Params) IsBroadcast(ca CommonAddr) bool

type TypeID uint8      // M_SP_NA_1 … F_SC_NB_1
func (t TypeID) String() string        // "M_ME_NC_1"
func (t TypeID) Description() string   // "Measured value, short floating point"
func (t TypeID) Supported() bool       // has an object model
func (t TypeID) HasTimeTag() bool
func (t TypeID) InControlDirection() bool
func (t TypeID) IsProcessCommand() bool
func (t TypeID) IsFileTransfer() bool
func (t TypeID) IsPrivate() bool

type Cause uint8       // CausePeriodic … CauseUnknownIOA
func (c Cause) String() string
func (c Cause) IsUnknown() bool        // 44..47

type IOA uint32
type CommonAddr uint16
const Broadcast CommonAddr = 0xFFFF

type Quality uint8
const (
	QualityGood           Quality = 0
	QualityOverflow       Quality = 0x01 // OV
	QualityElapsedInvalid Quality = 0x08 // EI (protection events)
	QualityBlocked        Quality = 0x10 // BL
	QualitySubstituted    Quality = 0x20 // SB
	QualityNotTopical     Quality = 0x40 // NT
	QualityInvalid        Quality = 0x80 // IV
)
func (q Quality) Good() bool
func (q Quality) Has(f Quality) bool
func (q Quality) String() string // "NT|IV", "good"

type DoubleState uint8   // DoubleIntermediate, DoubleOff, DoubleOn, DoubleIndeterminate
type StepDirection uint8 // StepLower, StepHigher
type CommandQualifier uint8 // QualifierNone, QualifierShortPulse, QualifierLongPulse, QualifierPersistent

type Normalized int16
func (n Normalized) Float64() float64        // [-1, 1)
func NormalizedFromFloat(f float64) Normalized // clamps

type QOI uint8           // QOIStation, QOIGroup1 … QOIGroup16
func QOIGroup(n int) QOI
func (q QOI) Cause() Cause

type Timestamp struct {
	time.Time
	Invalid     bool // IV
	Substituted bool // GEN
	SummerTime  bool // SU (CP56Time2a)
}
func At(t time.Time) Timestamp
func Now() Timestamp

type Params struct {
	K, W           int
	T0, T1, T2, T3 time.Duration
}
func DefaultParams() Params            // 12, 8, 30s, 15s, 10s, 20s
func (p Params) WithDefaults() Params  // fills zero K, W, T0, T1, T2
func (p Params) Validate() error       // 1 ≤ W ≤ K ≤ 32767, T2 < T1, T3 ≥ 0

const DefaultPort, DefaultTLSPort = 2404, 19998

type Format uint8 // FormatI, FormatS, FormatU
type UFunction uint8 // StartDTAct, StartDTCon, StopDTAct, StopDTCon, TestFRAct, TestFRCon
func (fn UFunction) Valid() bool
func (fn UFunction) IsAct() bool
func (fn UFunction) Confirmation() UFunction

type Frame struct {
	Format   Format
	SendSeq  uint16    // I
	RecvSeq  uint16    // I, S
	Function UFunction // U
	ASDU     []byte    // I
}
func NewI(sendSeq, recvSeq uint16, asdu []byte) Frame
func NewS(recvSeq uint16) Frame
func NewU(fn UFunction) Frame
func Parse(b []byte) (Frame, error)       // one whole APDU; ASDU aliases b
func ReadFrame(r io.Reader) (Frame, error) // reads exactly one APDU
func (f Frame) MarshalBinary() ([]byte, error)
func (f Frame) AppendBinary(b []byte) ([]byte, error)
func (f Frame) Len() int
func (f Frame) String() string // "I N(S)=2 N(R)=300 len=10"

const StartByte, MaxAPDULength, MaxASDULength, MaxFrameLength = 0x68, 253, 249, 255
const SeqModulus = 1 << 15
func SeqNext(n uint16) uint16
func SeqDiff(a, b uint16) int
func SeqAcks(nr, ack, next uint16) (n int, ok bool)