aznet

package module
v0.0.0-...-a979521 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 44 Imported by: 0

README

aznet

aznet logo

Go net.Conn and net.Listener interfaces over pluggable transports, with built-in drivers for Azure Storage services.

aznet has a driver-agnostic core that handles ordered, encrypted byte streams. Drivers provide the underlying transport; the built-in drivers use storage requests and polling. Applications use familiar Go I/O, but must account for storage latency, credential lifetime, finite buffers and cleanup ownership. Noise NN encrypts application frames without authenticating peer identity.

Start here

Follow Getting started to run a complete local round trip with Azurite and the examples/quickstart program. It prints hello aznet, verifies delivery and cleans up its demo resources.

To add the library to an existing Go project:

go get github.com/atsika/aznet

Use Go with automatic toolchain selection enabled. To try the built-in storage drivers, use an Azure Storage account or a local Azurite instance.

Full Close may delete unread session data. For delivery-sensitive responses, use CloseWrite and application-level completion before Close. Listener Close retains shared bootstrap resources; their administrator removes them explicitly after all namespace users stop. Neither credential renewal nor crash-proof remote cleanup is automatic.

Development

go test -race -count=1 ./...
go vet ./...

External-service tests require explicit opt-in; see the validation guide. The Starlight documentation uses Bun 1.4.2 and the committed docs/bun.lock. To install the locked dependencies and build:

cd docs
bun install --frozen-lockfile
bun run build
# For local editing:
bun run dev

The Driver/Transport registration mechanism remains the extension point. See the driver guide before changing ordering, retries or resource ownership.

License

MIT.

Credits

Built with the Noise Protocol and Azure SDK for Go.


Made with ❤️ by @_atsika

Documentation

Index

Constants

View Source
const (
	// MsgTypeData is for application data.
	MsgTypeData byte = 0x00
	// MsgTypePing is for keep-alive heartbeats.
	MsgTypePing byte = 0x01
	// MsgTypeFin is for graceful close.
	MsgTypeFin byte = 0x02
	// MsgTypeRotate is for rotation notifications.
	MsgTypeRotate byte = 0x03
)
View Source
const (
	// Default endpoint names for connection bootstrap
	DefaultHandshakeEndpoint = "handshake"
	DefaultTokenEndpoint     = "token"

	// DefaultReqPrefix is the default prefix for request channels.
	DefaultReqPrefix = "req"
	// DefaultResPrefix is the default prefix for response channels.
	DefaultResPrefix = "res"

	// DefaultSASExpiry is the default authorization expiry time.
	DefaultSASExpiry = 24 * time.Hour

	// DefaultFastPoll is the polling interval used during activity.
	// Adaptive polling backs off exponentially from FastPoll to DataPoll.
	DefaultFastPoll = 10 * time.Millisecond
	// DefaultDataPoll is the steady-state polling interval for idle connections.
	// At 500ms this produces ~7,200 read API calls per hour per connection.
	// Tune via WithDataPoll() to balance latency vs cost.
	DefaultDataPoll = 500 * time.Millisecond
	// DefaultAcceptPoll is the polling interval for listeners accepting incoming connections.
	DefaultAcceptPoll = 1 * time.Second
	// DefaultPingInterval is the interval between keep-alive heartbeats.
	DefaultPingInterval = 30 * time.Second

	// DefaultConnectTimeout is the maximum duration the client waits for connection acknowledgment.
	DefaultConnectTimeout = 30 * time.Second
	// DefaultIdleTimeout is the idle timeout before considering a peer dead.
	DefaultIdleTimeout = 5 * time.Minute
)
View Source
const FrameHeaderSize = 4 + 1 // 4 bytes length + 1 byte type
View Source
const MaxBlobBlockSize = 4 * 1024 * 1024

MaxBlobBlockSize is the maximum size of a single block in an Append Blob (4 MB).

View Source
const MaxBlocksPerBlob = 50000

MaxBlocksPerBlob is the maximum number of blocks per append blob.

View Source
const MaxQueueTextMessageSize = 64 * 1024

MaxQueuePayload is the maximum raw data size stored in a queue message (64 KB).

View Source
const MaxTableBinaryPropertySize = 64 * 1024

MaxTableBinaryPropertySize is the maximum size (64 KiB) for a single Edm.Binary property.

View Source
const MaxTableProperties = 15

MaxTableProperties is the number of binary properties we use to store a single large entity.

View Source
const NoiseOverhead = 4 + 16

NoiseOverhead is the encryption overhead: 4 bytes length prefix + 16 bytes AES-GCM tag.

Variables

View Source
var (
	// ErrUnsupportedScheme is returned when no registered driver exists for the requested URL scheme.
	ErrUnsupportedScheme = errors.New("unsupported scheme")
	// ErrClientCreationFailed is returned when an Azure service client cannot be created.
	ErrClientCreationFailed = errors.New("client creation failed")
	// ErrSASGenerationFailed is returned when a SAS token cannot be generated.
	ErrSASGenerationFailed = errors.New("failed to generate SAS token")
	// ErrMissingSAS is returned when required SAS tokens are missing from the URL.
	ErrMissingSAS = errors.New("missing handshake or token SAS in URL")
	// ErrInvalidSASEncoding is returned when a SAS token is not properly URL-encoded.
	ErrInvalidSASEncoding = errors.New("invalid SAS encoding")
	// ErrDecodeTokenFailed is returned when the JSON token payload cannot be decoded.
	ErrDecodeTokenFailed = errors.New("failed to decode token payload")
	// ErrWriteBufferFailed is returned when data cannot be written to an internal buffer.
	ErrWriteBufferFailed = errors.New("failed to write data to buffer")
	// ErrHandshakeExchangeFailed is returned when the initial handshake message cannot be sent or received.
	ErrHandshakeExchangeFailed = errors.New("failed to exchange handshake")
	// ErrInvalidConfig is returned when the provided options result in an invalid configuration.
	ErrInvalidConfig = errors.New("invalid configuration")
	// ErrInvalidProxy is returned when the address given to WithProxy is not an
	// http or https proxy URL.
	ErrInvalidProxy = errors.New("invalid proxy")
	// ErrProxyConnect is returned when the egress proxy cannot be reached or
	// refuses to open a tunnel.
	ErrProxyConnect = errors.New("proxy connect failed")
	// ErrProxyUnreachable accompanies ErrProxyConnect when no connection to the
	// proxy itself could be made (or secured), as opposed to a proxy that
	// answered and refused. Another proxy may then succeed.
	ErrProxyUnreachable = errors.New("proxy unreachable")
	// ErrProxyAuthRequired is returned when the proxy demands authentication
	// and no credentials were supplied.
	ErrProxyAuthRequired = errors.New("proxy requires credentials")
	// ErrProxyAuthUnsupported is returned when the proxy offers no
	// authentication scheme this build can answer.
	ErrProxyAuthUnsupported = errors.New("proxy authentication scheme unsupported")
	// ErrProxyAuthFailed is returned when the proxy rejects the credentials.
	ErrProxyAuthFailed = errors.New("proxy authentication failed")
	// ErrNoData is returned when no data is available to read.
	ErrNoData = errors.New("no data available")
	// ErrFrameTooLarge is returned when a queued frame exceeds one chunk.
	ErrFrameTooLarge = errors.New("frame exceeds chunk size")
	// ErrResourceBeingDeleted is returned when a bootstrap resource cannot be
	// created because Azure is still deleting one of the same name, which it does
	// for roughly 30-40s after a listener stops. Retrying later succeeds; the
	// library reports the condition and leaves that decision to the caller.
	ErrResourceBeingDeleted = errors.New("storage resource is being deleted, retry once Azure has released the name")
)
View Source
var (
	// ErrHandshakeFailed is returned when the Noise handshake fails.
	ErrHandshakeFailed = errors.New("handshake failed")
	// ErrHandshakeIncomplete is returned when the handshake is not complete.
	ErrHandshakeIncomplete = errors.New("handshake not complete")
	// ErrDecryptionFailed is returned when received data cannot be decrypted.
	ErrDecryptionFailed = errors.New("decryption failed")
	// ErrEncryptionFailed is returned when data cannot be encrypted.
	ErrEncryptionFailed = errors.New("encryption failed")
	// ErrNoiseInitFailed is returned when the Noise protocol state cannot be initialized.
	ErrNoiseInitFailed = errors.New("noise handshake initialization failed")
	// ErrNoiseMsgFailed is returned when a Noise handshake message cannot be created.
	ErrNoiseMsgFailed = errors.New("handshake message creation failed")
	// ErrChunkTooLarge is returned when a sealed chunk declares a length larger
	// than the transport can produce, which means the stream is corrupt.
	ErrChunkTooLarge = errors.New("sealed chunk exceeds transport maximum")
)
View Source
var ErrBootstrapDurationUnsupported = errors.New("driver does not support an independent bootstrap duration")

ErrBootstrapDurationUnsupported means a custom driver cannot issue bootstrap credentials with an independent duration. Its default ConnectionString still works.

View Source
var ErrBufferLimit = errors.New("aznet: byte buffer limit exceeded")

ErrBufferLimit is a terminal connection failure: retaining more bytes would exceed a configured allowance. Close still owns transport/session cleanup.

View Source
var ErrReassemblyOverflow = errors.New("azqueue: reassembly buffer overflow")

ErrReassemblyOverflow is returned when the azqueue reassembly buffer exceeds its byte allowance or maxPendingMessages. The failure is terminal.

View Source
var ErrReassemblyStalled = errors.New("azqueue: reassembly stalled on missing sequence")

ErrReassemblyStalled is returned when a sequence gap in the azqueue receive stream fails to close within the stall bound, i.e. a message was lost and the byte stream can never be completed.

Functions

func BuildFrame

func BuildFrame(writeBuf *bytes.Buffer, f Frame)

BuildFrame writes a framed message to the write buffer. Frame format: [4 bytes: length][1 byte: type][N bytes: payload] Caller must ensure writeBuf is protected from concurrent access.

func Dial

func Dial(network, address string, opts ...Option) (conn net.Conn, err error)

Dial is analogous to net.Dial. It takes a network type (e.g. "azblob") and an address (e.g. "https://account.blob.core.windows.net/?handshake=...").

func GetFactories

func GetFactories() []string

GetFactories returns a list of registered factory names.

func GetSessionExpiry

func GetSessionExpiry(conn net.Conn) (time.Time, bool)

GetSessionExpiry reads the optional connection capability without requiring callers to inspect credentials. Non-aznet connections can implement it too.

func Listen

func Listen(network, address string, opts ...Option) (net.Listener, error)

Listen is analogous to net.Listen. It takes a network type (e.g. "azblob") and an address (e.g. "account.blob.core.windows.net").

Listen fails with ErrResourceBeingDeleted when Azure is still deleting resources left by a previous listener of the same name. That is a transient condition, but waiting it out is the caller's decision, not the library's.

func RegisterFactory

func RegisterFactory(scheme string, factory Factory)

RegisterFactory registers a factory for the given scheme (e.g., "azblob").

func UnregisterFactory

func UnregisterFactory(scheme string)

UnregisterFactory removes the factory registration.

Types

type AcceptError

type AcceptError struct {
	Op  string
	Err error
}

AcceptError identifies the failed setup operation and preserves the underlying error (including SDK response details). Temporary reports whether a caller may retry Accept; Accept itself only retries empty polls.

func (*AcceptError) Error

func (e *AcceptError) Error() string

func (*AcceptError) Temporary

func (e *AcceptError) Temporary() bool

func (*AcceptError) Timeout

func (e *AcceptError) Timeout() bool

func (*AcceptError) Unwrap

func (e *AcceptError) Unwrap() error

type AdaptivePoll

type AdaptivePoll struct {
	Cur    time.Duration
	Fast   time.Duration
	Steady time.Duration
	// contains filtered or unexported fields
}

AdaptivePoll implements an exponential back-off sleep utility. Call Reset() after any activity to return to the fast interval. Safe for concurrent use.

func NewAdaptivePoll

func NewAdaptivePoll(fast, steady time.Duration) *AdaptivePoll

NewAdaptivePoll builds a poller initialized to the fast interval.

func (*AdaptivePoll) Next

func (p *AdaptivePoll) Next() time.Duration

Next returns the interval to wait before the next poll, backing off exponentially up to Steady. It returns 0 once after Reset so activity resumes at full speed. The caller does the waiting.

func (*AdaptivePoll) Reset

func (p *AdaptivePoll) Reset()

Reset moves the current interval back to the fast value.

type BootstrapTokenIssuer

type BootstrapTokenIssuer interface {
	CreateBootstrapTokensFor(time.Duration) (handshake, token string, err error)
}

BootstrapTokenIssuer is an optional Driver capability. It issues credentials for one bootstrap URL without changing the driver's session policy.

type BufferLimits

type BufferLimits struct {
	Pending, Decrypted, Write, Retry, WriteChunks int
}

BufferLimits bounds live bytes per connection in each ownership stage. Pending bounds received ciphertext and, separately, Queue reassembly. Decrypted bounds framed plaintext awaiting Read. Write bounds queued framed plaintext (including control frames). WriteChunks, when positive, further caps Write at that many of the transport's chunks: queued bytes leave one chunk at a time, so a small write waits behind every chunk queued ahead of it. Retry bounds one sealed outgoing chunk. Encryption/decryption scratch and allocator capacity are additional, finite storage; these allowances are not a process heap or cloud storage quota.

func DefaultBufferLimits

func DefaultBufferLimits() BufferLimits

DefaultBufferLimits accommodates two maximum Blob chunks on receive, and one on retry. Large application writes are flushed in bounded batches.

type Buffers

type Buffers struct {
	Enc   []byte // Encryption scratch space
	Dec   []byte // Decryption scratch space
	Read  bytes.Buffer
	Write bytes.Buffer
	Noise bytes.Buffer
}

Buffers encapsulates the internal bytes.Buffer instances used by a connection.

type Config

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

Config holds runtime settings for a connection or listener. Zero value yields sane defaults via defaultConfig(). Users should modify it through functional options.

func (*Config) SASTimes

func (c *Config) SASTimes() (start, end time.Time)

SASTimes returns issuance times for session credentials. Custom drivers can use this policy while exposing unknown expiry if they cannot report exact issuance.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks if the configuration is sane and valid.

type Conn

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

Conn implements net.Conn.

func (*Conn) Close

func (c *Conn) Close() error

Close attempts accepted data followed by FIN within 250 ms, then cancels I/O. Session cleanup then has two independently bounded two-second operations. A timeout means delivery, transport teardown or resource cleanup is unconfirmed. On an accepted connection, Close deletes session storage: uploading bytes does not acknowledge peer consumption. Use CloseWrite and wait for application-level completion before Close when the peer must receive the final response.

func (*Conn) CloseWrite

func (c *Conn) CloseWrite() error

CloseWrite shuts down the writing side of the connection. It sends a FIN frame to the peer to indicate that no more data will be sent.

func (*Conn) GetMetrics

func (c *Conn) GetMetrics() Metrics

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

func (*Conn) MTU

func (c *Conn) MTU() int

MTU returns the maximum number of application bytes that can fit in a single transport frame for the current connection.

func (*Conn) Read

func (c *Conn) Read(p []byte) (n int, err error)

func (*Conn) RemoteAddr

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

func (*Conn) SessionExpiry

func (c *Conn) SessionExpiry() (time.Time, bool)

SessionExpiry returns the exact earliest required session-token expiration. False means unknown (for example, a custom driver without issuance metadata). Expiration is informational: it is not a liveness promise or a close timer.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write

func (c *Conn) Write(p []byte) (int, error)

Write queues p and returns once it is accepted; flushLoop sends it in order. Bytes queued while a chunk is in flight leave together in the next chunk, so small writes share storage requests without a coalescing timer. Write blocks only while BufferLimits.Write is full. n reports bytes the connection owns, including on error; callers must only resubmit p[n:]. A failed background send is returned by the next Write (n == 0) and its retained ciphertext is resent on the following flush. Write(nil) and CloseWrite wait for everything queued to be sent.

type DefaultMetrics

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

DefaultMetrics uses atomic aggregate counters and a synchronized attempt map.

func NewDefaultMetrics

func NewDefaultMetrics() *DefaultMetrics

NewDefaultMetrics creates a new DefaultMetrics instance.

func (*DefaultMetrics) GetBytesReceived

func (m *DefaultMetrics) GetBytesReceived() int64

func (*DefaultMetrics) GetBytesSent

func (m *DefaultMetrics) GetBytesSent() int64

func (*DefaultMetrics) GetDeleteTransactionCount

func (m *DefaultMetrics) GetDeleteTransactionCount() int64

func (*DefaultMetrics) GetListTransactionCount

func (m *DefaultMetrics) GetListTransactionCount() int64

func (*DefaultMetrics) GetReadTransactionCount

func (m *DefaultMetrics) GetReadTransactionCount() int64

func (*DefaultMetrics) GetWriteTransactionCount

func (m *DefaultMetrics) GetWriteTransactionCount() int64

func (*DefaultMetrics) IncrementBytesReceived

func (m *DefaultMetrics) IncrementBytesReceived(n int64)

func (*DefaultMetrics) IncrementBytesSent

func (m *DefaultMetrics) IncrementBytesSent(n int64)

func (*DefaultMetrics) IncrementDeleteTransaction

func (m *DefaultMetrics) IncrementDeleteTransaction()

func (*DefaultMetrics) IncrementListTransaction

func (m *DefaultMetrics) IncrementListTransaction()

func (*DefaultMetrics) IncrementReadTransaction

func (m *DefaultMetrics) IncrementReadTransaction()

func (*DefaultMetrics) IncrementWriteTransaction

func (m *DefaultMetrics) IncrementWriteTransaction()

func (*DefaultMetrics) RecordRequest

func (m *DefaultMetrics) RecordRequest(a RequestAttempt)

RecordRequest records one completed SDK pipeline attempt.

func (*DefaultMetrics) RequestCounts

func (m *DefaultMetrics) RequestCounts() map[RequestAttempt]int64

RequestCounts returns an independent snapshot of completed SDK attempts.

type Driver

type Driver interface {
	// Handshake operations
	PostHandshake(ctx context.Context, connID string, data []byte) error
	GetHandshakes(ctx context.Context) ([]Handshake, error)
	DeleteHandshake(ctx context.Context, id string) error

	// Token exchange operations
	PostToken(ctx context.Context, connID string, data []byte) error
	GetToken(ctx context.Context, connID string) ([]byte, error)
	DeleteToken(ctx context.Context, connID string) error

	// Session lifecycle. The listener owns connID before this call and invokes
	// CleanupSession even when acquisition fails partway through.
	CreateSession(ctx context.Context, connID string) (SessionTokens, error)
	CreateBootstrapTokens() (hSAS, tSAS string, err error)

	// NewTransport creates a data transporter for an established session.
	NewTransport(ctx context.Context, connID string, tokens SessionTokens, isInitiator bool) (Transport, error)

	// CleanupBootstrap removes shared bootstrap resources (handshake/token endpoints).
	CleanupBootstrap(ctx context.Context) error
	// CleanupSession removes all per-connection resources, including partial
	// acquisitions. It must be idempotent and return deletion failures.
	CleanupSession(ctx context.Context, connID string) error
}

Driver defines how a driver handles the initial connection setup.

type Endpoint

type Endpoint struct {
	URL     *url.URL
	Account string
	Key     string
	IsAzure bool
}

Endpoint represents an aznet endpoint.

func NewEndpoint

func NewEndpoint(u *url.URL) *Endpoint

NewEndpoint creates a new Endpoint from a URL.

func (*Endpoint) BuildConnURL

func (e *Endpoint) BuildConnURL(cfg *Config, handshakeSAS, tokenSAS string) string

BuildConnURL constructs the final aznet connection URL with base64 encoded SAS tokens.

func (*Endpoint) JoinURL

func (e *Endpoint) JoinURL(resource, sas string) string

JoinURL joins the base service URL with a resource name and optional SAS token.

func (*Endpoint) ParseSAS

func (e *Endpoint) ParseSAS(cfg *Config) (string, string, error)

ParseSAS parses the handshake and token SAS tokens from the URL query. It returns the decoded SAS strings (without leading '?').

func (*Endpoint) ServiceURL

func (e *Endpoint) ServiceURL() string

ServiceURL returns the base URL for the Azure Storage service.

type Factory

type Factory interface {
	// NewDriver creates a Driver for the given endpoint and config.
	NewDriver(ep *Endpoint, cfg *Config) (Driver, error)
}

Factory is an interface for creating a Driver implementation.

type Frame

type Frame struct {
	Payload []byte
	Length  uint32
	Type    byte
}

Frame represents a single message unit.

type Handshake

type Handshake struct {
	ID      string // handshake identifier (used for cleanup)
	Payload []byte // The raw Noise handshake message
}

Handshake represents a discovered connection request.

type Listener

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

Listener implements net.Listener. Close owns sessions, not the shared bootstrap namespace; its administrator may explicitly call CleanupBootstrap.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

func (*Listener) CleanupBootstrap

func (l *Listener) CleanupBootstrap(ctx context.Context) error

CleanupBootstrap removes the shared discovery namespace. Call only after all users of that namespace have stopped. It is deliberately independent of Close.

func (*Listener) Close

func (l *Listener) Close() error

func (*Listener) ConnectionString

func (l *Listener) ConnectionString() (string, error)

ConnectionString returns bootstrap credentials for this listener.

func (*Listener) ConnectionStringFor

func (l *Listener) ConnectionStringFor(duration time.Duration) (string, error)

ConnectionStringFor issues bootstrap credentials valid for duration from their issuance time. It does not mutate listener/session configuration or renew any existing credential. Azure SAS timestamps have whole-second precision.

type Metrics

type Metrics interface {
	IncrementWriteTransaction()
	IncrementReadTransaction()
	IncrementListTransaction()
	IncrementDeleteTransaction()
	IncrementBytesSent(n int64)
	IncrementBytesReceived(n int64)

	GetWriteTransactionCount() int64
	GetReadTransactionCount() int64
	GetListTransactionCount() int64
	GetDeleteTransactionCount() int64
	GetBytesSent() int64
	GetBytesReceived() int64
}

Metrics is an interface for tracking connection statistics. Azure adapters count every SDK attempt, including failures and retries. Byte counters track successful transport payload writes and consumed reads, including framing/handshakes; they are neither HTTP wire bytes nor billed usage.

func GetMetrics

func GetMetrics(c net.Conn) Metrics

GetMetrics returns the metrics from a connection if it supports metrics tracking. It returns nil if the connection doesn't support metrics.

type Noise

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

Noise encapsulates the Noise Protocol handshake state and cipher suite.

func NewNoiseClient

func NewNoiseClient() (*Noise, error)

NewNoiseClient creates a new Noise Protocol handshake as the initiator (client). It uses the NN pattern (no static keys, anonymous connection).

func NewNoiseServer

func NewNoiseServer() (*Noise, error)

NewNoiseServer creates a new Noise Protocol handshake as the responder (server). It uses the NN pattern (no static keys, anonymous connection).

func (*Noise) DecryptData

func (nh *Noise) DecryptData(dst, ciphertext []byte) ([]byte, error)

DecryptData decrypts application data using the established session cipher.

func (*Noise) EncryptData

func (nh *Noise) EncryptData(dst, plaintext []byte) ([]byte, error)

EncryptData encrypts application data using the established session cipher.

func (*Noise) GetCipherStates

func (nh *Noise) GetCipherStates() (send, recv *noise.CipherState, err error)

GetCipherStates returns the established cipher states for encrypting/decrypting data. send is for sending, recv is for receiving.

func (*Noise) IsComplete

func (nh *Noise) IsComplete() bool

IsComplete returns true if the handshake is complete and session keys are established.

func (*Noise) IsInitiator

func (nh *Noise) IsInitiator() bool

IsInitiator returns true if the handshake is the initiator.

func (*Noise) ReadMessage

func (nh *Noise) ReadMessage(msg []byte) ([]byte, error)

ReadMessage processes a handshake message from the peer, decrypting the payload. It returns the decrypted payload.

func (*Noise) SealData

func (nh *Noise) SealData(dst, plaintext []byte) ([]byte, error)

SealData encrypts plaintext and prepends a 4-byte big-endian length. It uses the provided dst buffer if it has enough capacity.

func (*Noise) UnsealData

func (nh *Noise) UnsealData(dst, data []byte, maxChunk int) (plaintext, remaining []byte, err error)

UnsealData extracts and decrypts one Noise chunk from data, returning the plaintext in dst and the unconsumed remainder. maxChunk bounds the sealed chunk size (0 disables): a larger declared length is corrupt, and reporting it as io.ErrShortBuffer would leave the caller buffering for bytes never coming.

func (*Noise) WriteMessage

func (nh *Noise) WriteMessage(payload []byte) ([]byte, error)

WriteMessage creates the next handshake message, encrypting the payload. It returns the message to send to the peer.

type Option

type Option func(*Config)

Option defines a functional option for Listen/Dial.

func WithAcceptPoll

func WithAcceptPoll(d time.Duration) Option

WithAcceptPoll sets how frequently the listener scans for new connections.

func WithBufferLimits

func WithBufferLimits(limits BufferLimits) Option

WithBufferLimits replaces positive allowances. Write reserves one FIN header; Write and Retry must each fit a framed byte (plus encryption for Retry). Smaller receive allowances may reject a peer's larger chunks terminally.

func WithConnectTimeout

func WithConnectTimeout(d time.Duration) Option

WithConnectTimeout bounds client setup and the lifetime of Queue tokens issued by a listener. Zero or negative values leave the default unchanged.

func WithContext

func WithContext(ctx context.Context) Option

WithContext sets the base context for all network/SDK calls initiated by Listen/Dial. Useful for cancellation or shared tracing.

func WithDataPoll

func WithDataPoll(d time.Duration) Option

WithDataPoll sets how often established connections poll for data.

func WithEndpoints

func WithEndpoints(handshake, token string) Option

WithEndpoints allows overriding the default handshake and token endpoints used during the connection bootstrap phase.

func WithFastPoll

func WithFastPoll(d time.Duration) Option

WithFastPoll sets the polling interval used when data is actively flowing.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the grace period after which background janitors purge half-closed connections that never completed a FIN handshake. Zero disables automatic cleanup.

func WithMetrics

func WithMetrics(metrics Metrics) Option

WithMetrics sets a custom metrics implementation for tracking connection statistics. If not provided, a default implementation with atomic counters will be used.

func WithPing

func WithPing(d time.Duration) Option

WithPing sets the keep-alive heartbeat cadence. Zero disables keep-alive.

func WithPrefixes

func WithPrefixes(reqPrefix, resPrefix string) Option

WithPrefixes sets the prefixes that drivers use when creating per-connection request/response artefacts (e.g. blobs or queues).

func WithProxy

func WithProxy(address string, auth ProxyAuth, user, pass string) Option

WithProxy sends every storage request through the HTTP egress proxy at address, using HTTP CONNECT. address is a URL such as "http://proxy.corp:8080"; a bare host:port means http. user and pass may be empty, in which case credentials in the address are used, and failing that the proxy is tried without any (see ProxyConfig.User).

Only HTTP and HTTPS proxies are supported. Plain-HTTP storage endpoints (such as an emulator) are reached through CONNECT too, which most proxies restrict to port 443.

func WithProxyFunc

func WithProxyFunc(fn ProxyFunc) Option

WithProxyFunc is WithProxy with the proxy chosen per connection.

func WithProxyLog

func WithProxyLog(logf func(format string, args ...any)) Option

WithProxyLog reports how connections are made through the proxy: which proxy was chosen, the CONNECT exchange, the schemes the proxy offers and which one answered. Credentials, tokens and user names are never included. It has no effect without WithProxy or WithProxyFunc, and may be given in any order.

func WithSASExpiry

func WithSASExpiry(d time.Duration) Option

WithSASExpiry sets both legacy default bootstrap and session durations. Prefer WithSessionDuration plus ConnectionStringFor for independent policies. Durations below one second fail configuration validation.

func WithSessionDuration

func WithSessionDuration(d time.Duration) Option

WithSessionDuration sets the validity of newly issued session credentials. It does not change default bootstrap validity or existing sessions. The default is 24 hours. Durations below one second fail configuration validation.

type ProxyAuth

type ProxyAuth int

ProxyAuth selects how aznet authenticates to an egress proxy.

const (
	// ProxyAuto picks the strongest scheme the proxy offers that the available
	// credentials allow: Negotiate, then NTLM, then Basic. Nothing is sent
	// until the proxy has said which schemes it accepts.
	ProxyAuto ProxyAuth = iota
	// ProxyBasic sends the credentials with the first request. Use it only
	// when the proxy is known to ask for Basic.
	ProxyBasic
	// ProxyNTLM authenticates with NTLM and explicit credentials.
	ProxyNTLM
	// ProxyNegotiate authenticates with SPNEGO (Kerberos, falling back to NTLM
	// where the platform provides it).
	ProxyNegotiate
)

func (ProxyAuth) String

func (a ProxyAuth) String() string

type ProxyConfig

type ProxyConfig struct {
	// URL is the proxy address. Its scheme is http or https (TLS to the proxy
	// itself); any credentials in its user information are used when User and
	// Pass are empty.
	URL *url.URL
	// Auth selects the authentication scheme.
	Auth ProxyAuth
	// User and Pass are the proxy credentials. NTLM accepts DOMAIN\user and
	// user@domain. Both empty means no explicit credentials: Negotiate then
	// uses the identity of the running process where the platform allows it.
	User, Pass string
	// SPN is the Kerberos service name, HTTP/ plus the proxy's host name when
	// empty. Set it when the proxy is reached by an alias or an address.
	SPN string
}

ProxyConfig describes the egress proxy to use for one connection.

type ProxyDialer

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

ProxyDialer opens TCP connections the way storage requests are opened under WithProxyFunc: the ProxyFunc picks a proxy for each destination, a nil config connects directly, and anything else is reached through HTTP CONNECT with the same authentication. Use it for traffic of your own that must leave through the same egress proxy. It is safe for concurrent use.

func NewProxyDialer

func NewProxyDialer(fn ProxyFunc, logf func(string, ...any)) *ProxyDialer

NewProxyDialer returns a ProxyDialer that asks fn for the proxy of every connection. logf, which may be nil, traces it as WithProxyLog does.

func (*ProxyDialer) DialContext

func (d *ProxyDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext connects to addr, a host:port, over TCP. The returned connection supports CloseWrite whenever the underlying one does, so a tunnel through the proxy can be half-closed like a direct connection.

type ProxyFunc

type ProxyFunc func(ctx context.Context, target *url.URL) (*ProxyConfig, error)

ProxyFunc chooses the egress proxy for a new connection to target, a URL whose scheme is https for port 443 and http otherwise. A nil config, with a nil error, connects directly. It is called for every new connection, so a reconnect can pick a different proxy.

type RequestAttempt

type RequestAttempt struct {
	Driver     string
	Operation  string
	Method     string
	StatusCode int
	Retry      bool
	Failed     bool
}

RequestAttempt identifies one SDK pipeline attempt. Labels never contain URLs, resource names, tokens or error text. StatusCode is zero without a response. Retry is true only for an SDK retry, not a new application-level invocation. Failed includes transport errors and HTTP status codes >= 400. A successful batch HTTP response may still contain failed operations inside its body.

type RequestMetrics

type RequestMetrics interface{ RecordRequest(RequestAttempt) }

RequestMetrics is an optional extension to Metrics for detailed SDK attempts. RecordRequest must be safe for concurrent use and must not block I/O. Drivers that do not use Azure's SDK can implement their own instrumentation.

type Rotator

type Rotator interface {
	ShouldRotate() bool
	RotateTX(ctx context.Context) error
	RotateRX() error
}

Rotator is optionally implemented by transports that need resource rotation (e.g., blob append blobs have a 50,000 block limit). Core handles rotation signaling automatically when this interface is satisfied.

type ServiceAddr

type ServiceAddr struct {
	Net      string // driver name (e.g. "azblob")
	Endpoint string // base service URL
	Resource string // resource identifier (container/queue/table + sub-resource)
}

ServiceAddr is a reusable net.Addr implementation for all drivers.

func (ServiceAddr) Network

func (a ServiceAddr) Network() string

func (ServiceAddr) String

func (a ServiceAddr) String() string

type SessionTokens

type SessionTokens struct {
	Req string `json:"req"`
	Res string `json:"res"`
	// ExpiresAt is the earliest expiry of all required session credentials.
	// Zero means unknown; drivers must not infer it from connection creation time.
	ExpiresAt time.Time `json:"expires_at,omitzero"`
}

SessionTokens represents the session-specific tokens/SAS exchanged after handshake.

type Transport

type Transport interface {
	// WriteRaw sends raw bytes to the peer. seq is the chunk number, reused on a
	// retry so the driver can keep the write idempotent. Conn serializes calls,
	// starts at zero, and advances only after success; retries use identical bytes.
	// It must honor ctx.
	WriteRaw(ctx context.Context, seq uint64, data io.ReadSeeker) error
	// ReadRaw attempts to read raw bytes from the peer. The request and returned
	// stream must honor ctx; closing the stream must unblock a pending Read.
	ReadRaw(ctx context.Context) (io.ReadCloser, error)
	// Close terminates the transport.
	Close() error
	// LocalAddr returns the local network address.
	LocalAddr() net.Addr
	// RemoteAddr returns the remote network address.
	RemoteAddr() net.Addr
	// MaxRawSize returns the maximum raw capacity of the transport in bytes.
	// It must be constant for the lifetime of the transport.
	MaxRawSize() int
}

Transport is the raw byte-exchange interface implemented by drivers.

Directories

Path Synopsis
cmd
azurl command
examples
echo/client command
echo/server command
metrics/client command
metrics/server command
quickstart command
A one-connection demonstration.
A one-connection demonstration.
tests
proxylab/adprobe command
Command adprobe logs in to a Kerberos realm with gokrb5, the library aznet uses on macOS and Linux, and optionally asks for a service ticket.
Command adprobe logs in to a Kerberos realm with gokrb5, the library aznet uses on macOS and Linux, and optionally asks for a service ticket.
proxylab/kerbprobe command
Command kerbprobe asks Windows' Kerberos SSPI package for a service ticket with explicit credentials, to show whether the client can reach a KDC and get a ticket, independently of any proxy.
Command kerbprobe asks Windows' Kerberos SSPI package for a service ticket with explicit credentials, to show whether the client can reach a KDC and get a ticket, independently of any proxy.
proxylab/netonly command
Command netonly runs a command with network credentials of another account, like `runas /netonly`, but takes the password from the environment so it can be used from a non-interactive session (SSH).
Command netonly runs a command with network credentials of another account, like `runas /netonly`, but takes the password from the environment so it can be used from a non-interactive session (SSH).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL