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

	// Identity specifies the identity presented to the remote peer during
	// connection negotiation.
	//
	// When set to non-nil, an 'a=identity' attribute is attached to the SDP offer
	// and used to authenticate the client and bind its identity to the WebRTC peer
	// connection.
	//
	// When set to nil, no identity assertion is included in the offer.
	Identity *Identity
	// VerifyServerToken verifies the token contained in a server's identity
	// assertion and returns the public key populated in its 'cpk' claim.
	//
	// The returned public key is used to verify the fingerprint assertion
	// carried in the server answer's 'a=identity' attribute.
	//
	// When [Dialer.AllowIdentitylessServer] is set to true, VerifyServerToken may never be called.
	//
	// By default, this is set to a function that only extracts the public key
	// from the token's 'cpk' claim and trusts it unconditionally.
	VerifyServerToken func(ctx context.Context, token, domain string) (*ecdsa.PublicKey, error)

	// AllowIdentitylessServer specifies whether to allow answer SDPs without an
	// 'a=identity' attribute.
	//
	// When set to false, the server must present a valid identity assertion.
	// When set to true, unauthenticated servers are allowed to establish connections.
	//
	// This may be useful when connecting to legacy or custom implementations.
	AllowIdentitylessServer bool

	// ICEGatherPolicy limits which local ICE candidates are gathered for the
	// connection.
	//
	// It may be used to restrict connectivity to specific candidate types, such
	// as relayed candidates from TURN servers only.
	ICEGatherPolicy webrtc.ICEGatherPolicy

	// DisableTrickleICE disables trickle ICE for connection negotiation.
	//
	// When set to true, the dialer waits for ICE gathering to complete and embeds
	// all local candidates in the initial offer SDP. Otherwise, candidates are
	// signaled incrementally as separate [SignalTypeCandidate] signals after the
	// offer is sent.
	//
	// This may slow connection establishment because the initial offer cannot be
	// sent until candidate gathering completes.
	//
	// This behavior can be seen when connecting to dedicated servers with the
	// 'nethernet-disable-trickle-ice' setting property set to 'true'.
	DisableTrickleICE bool
}

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

type Identity struct {
	// PrivateKey is the private key corresponding to the 'cpk' claim contained
	// in [Identity.Token].
	//
	// It is used to sign the SDP fingerprint assertion carried in the 'a=identity'
	// attribute, binding the authenticated identity to the WebRTC peer connection.
	//
	// For server identities, this key is also used to self-sign [Identity.Token].
	PrivateKey *ecdsa.PrivateKey
	// Token is the JWT token for this identity.
	// For client identities, this token is issued by Minecraft's authorization service.
	// For server identities, this token is self-signed by the server using the [Identity.PrivateKey].
	// The JWT token must contain the corresponding public key for [Identity.PrivateKey] as the 'cpk' claim.
	Token string
	// Domain is the domain name that may be surfaced to players on first join when
	// connecting via an insecure (non-TLS) context.
	// For server identities, this can be "self", as observed on Bedrock Dedicated Server.
	Domain string
}

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, context.CancelFunc)

	// 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, context.CancelFunc)

	// IssueServerIdentity issues the identity presented to clients in SDP answers.
	// The returned identity is used to produce the server-side 'a=identity' attribute.
	// The token must contain the public key corresponding the [Identity.PrivateKey] in
	// its 'cpk' claim.
	//
	// If set to nil, it is replaced to a function that automatically generates a
	// temporary identity. Because the generated key is not saved, clients using
	// Trust On First Use (TOFU) may treat each server restart as a different identity.
	IssueServerIdentity func(ctx context.Context) (*Identity, error)

	// VerifyClientToken verifies the token contained in a client's identity
	// assertion and returns the public key populated in its 'cpk' claim.
	// The returned public key is used to verify the fingerprint assertion
	// carried in the client offer's 'a=identity' attribute.
	//
	// Unlike identity tokens issued by servers, client tokens are issued by
	// Minecraft's authorization service and include additional information
	// such as gamertag and XUID.
	//
	// These claims may be used to implement allowlists or blocklists.
	// However, the same checks should also be enforced by the Minecraft protocol
	// layer, since a malicious client may present a different token that
	// is bound to the same public key.
	//
	// By default, this is set to a function that only extracts the public key
	// from the 'cpk' claim in the JWT token. It does not perform cryptographic
	// verification using the public keys exposed by Minecraft's authorization service,
	// as this library does not provide access to that endpoint.
	//
	// The default verifier only binds the SDP identity assertion to the public
	// key in the token. It is appropriate for Bedrock integrations only when the
	// Minecraft protocol layer also verifies the Login packet token and checks
	// that the same public key was used in its 'cpk' claim. Servers that rely on
	// NetherNet identity alone should provide a verifier that validates token
	// issuance.
	VerifyClientToken func(ctx context.Context, token string) (*ecdsa.PublicKey, error)

	// AllowAnonymous determines whether SDP offers without an 'a=identity'
	// attribute are accepted.
	// When set to false, all incoming connections must provide a valid identity
	// assertion. When set to true, unauthenticated peers are allowed to connect.
	//
	// The zero value is false. Set this explicitly for offline/custom clients
	// that do not send identity assertions.
	//
	// This may be useful for implementing offline-mode servers, but it removes
	// the identity binding normally provided by NetherNet and may allow replay
	// attacks against upstream protocols. It should therefore only be enabled
	// in trusted environments.
	AllowAnonymous bool

	// ICEGatherPolicy limits which local ICE candidates are gathered for
	// accepted connections.
	//
	// It may be used to restrict connectivity to specific candidate types, such
	// as relayed candidates from TURN servers only.
	ICEGatherPolicy webrtc.ICEGatherPolicy

	// DisableTrickleICE disables trickle ICE for connection negotiation.
	//
	// When set to true, the listener waits for ICE gathering to complete and embeds
	// all local candidates in the answer SDP. Otherwise, candidates are signaled
	// incrementally as separate [SignalTypeCandidate] signals after the answer is
	// sent.
	//
	// This may slow connection establishment because the answer cannot be sent
	// until candidate gathering completes.
	//
	// This behavior can be seen on dedicated servers with the
	// 'nethernet-disable-trickle-ice' setting property set to 'true'.
	DisableTrickleICE bool
}

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

type MessageReliability uint8

type Notifier interface {
	// NotifySignal handles an incoming Signal from a remote network. It must
	// return promptly and must not block the Signaling implementation. It
	// reports whether the Signal was accepted for processing.
	NotifySignal(signal *Signal) bool
}

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 n for receiving incoming signals from remote networks.
	// Each call creates an independent subscription; incoming signals are
	// broadcast to all active subscriptions, not load-balanced between them.
	// The returned stop function unregisters n and must be safe to call
	// multiple times.
	Notify(n Notifier) (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)
}