nethernet

type Addr struct {
	// ConnectionID is a unique ID assigned to a connection. It is generated by the client and
	// used in Signals signaled between clients and servers to uniquely reference a specific connection.
	ConnectionID uint64

	// NetworkID is a unique ID for the NetherNet network.
	NetworkID string

	// Candidates contains a list of ICE candidates. These candidates are either gathered locally or
	// signaled from a remote connection. ICE candidates are used to determine the UDP/TCP addresses
	// for establishing ICE transport and can be used to determine the network address of the connection.
	Candidates []webrtc.ICECandidate

	// SelectedCandidate is the candidate selected to connect with the ICE transport within a Conn.
	// An ICE candidate may be used to determine the UDP/TCP address of the connection. It may be nil
	// if the Conn has been closed, or if the Conn has encountered an error when obtaining the selected
	// ICE candidate pair.
	SelectedCandidate *webrtc.ICECandidate
}

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

type Credentials struct {
	ExpirationInSeconds int         `json:"ExpirationInSeconds"`
	ICEServers          []ICEServer `json:"TurnAuthServers"`
}

type Dialer struct {
	// ConnectionID is the unique ID of a Conn being established. If zero, a random value will be automatically
	// set from [rand.Uint64].
	ConnectionID uint64

	// Log is used for logging messages at various log levels. If nil, the default [slog.Logger] will be automatically
	// set from [slog.Default]. Log will be extended when a Conn is being established by [Dialer] with additional attributes
	// such as the connection ID and network ID, and will have a 'src' attribute set to 'dialer' to mark that the Conn
	// has been negotiated by Dialer.
	Log *slog.Logger

	// API specifies custom configuration for WebRTC transports and data channels. If nil, a new [webrtc.API] will be
	// set from [webrtc.NewAPI]. The [webrtc.SettingEngine] of the API should not allow detaching data channels, as it requires
	// additional steps on the Conn (which cannot be determined by the Conn).
	API *webrtc.API
}

type ICEServer struct {
	Username string   `json:"Username"`
	Password string   `json:"Password"`
	URLs     []string `json:"Urls"`
}

type ListenConfig struct {
	// Log is used for logging messages at various levels. If nil, the default [slog.Logger] will be set from
	// [slog.Default]. Log will be extended when a Conn is being accepted by [Listener.Accept] with additional
	// attributes such as the connection ID and network ID, and will have a 'src' attribute set to 'listener'
	// to mark that the Conn has been negotiated by Listener.
	Log *slog.Logger

	// API specifies custom configuration for WebRTC transports and data channels. If nil, a new [webrtc.API] will
	// be set from [webrtc.NewAPI]. The [webrtc.SettingEngine] of the API should not allow detaching data channels,
	// as it requires additional steps on the Conn (which cannot be determined by the Conn).
	API *webrtc.API

	// ConnContext provides a [context.Context] for starting the ICE, DTLS, and SCTP transports of the Conn. If nil,
	// a default [context.Context] with 5 seconds timeout will be used. The parent [context.Context] may be used to
	// create a [context.Context] to be returned (likely using [context.WithCancel] or [context.WithTimeout]).
	ConnContext func(parent context.Context, conn *Conn) context.Context

	// NegotiationContext provides a [context.Context] for the negotiation. If nil, a default [context.Context]
	// with 5 seconds timeout will be used. The parent [context.Context] may be used to create a [context.Context]
	// to be returned (likely using [context.WithCancel] or [context.WithTimeout]). If the deadline of the context
	// is exceeded, a Signal of SignalTypeError with ErrorCodeNegotiationTimeoutWaitingForAccept will be signaled back.
	NegotiationContext func(parent context.Context) context.Context
}

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

type MessageReliability uint8

type Signal struct {
	// Type indicates the type of Signal. It is one of constants defined above.
	Type string

	// ConnectionID is the unique ID of the connection that has sent the Signal.
	// It is used by both server and client to uniquely reference the connection.
	ConnectionID uint64

	// Data is the actual data of the Signal, represented as a string.
	Data string

	// NetworkID is the internal ID used by Signaling to reference a remote network and not
	// included to the String representation to be signaled to the remote network. If sent by
	// a server, it represents the sender ID. If sent by a client, it represents the recipient ID.
	NetworkID string
}

type Signaling interface {
	// Signal sends a Signal to a remote network referenced by [Signal.NetworkID].
	// The [context.Context] is used to cancel waiting for the acknowledgement from
	// the signaling server as soon as possible.
	Signal(ctx context.Context, signal *Signal) error

	// Notify registers a channel so that can be used to receive incoming signals from remote networks.
	// It also returns a function to stop receiving signals on the channel.
	Notify(ch chan<- *Signal) (stop func())

	// Context returns a context for Signaling that is canceled optionally with a cause when a fatal
	// error has occurred on the signaling server. It is used by both Dialer and Listener to notify
	// a fatal error so they can no longer listen or dial for a connection that is no longer notified.
	Context() context.Context

	// Credentials blocks until Credentials are received by Signaling, and returns them. If Signaling
	// does not support returning Credentials, it will return nil. Credentials are typically received
	// from a WebSocket connection. The [context.Context] may be used to cancel the blocking.
	Credentials(ctx context.Context) (*Credentials, error)

	// NetworkID returns the local network ID of Signaling. It is used by Listener to obtain its local
	// network ID.
	NetworkID() string

	// PongData sets the server data in the format of a RakNet pong response. It is used by the Listener
	// to respond to a ping request in the correct format.
	PongData(b []byte)
}