Documentation
¶
Index ¶
- Constants
- Variables
- func BuildFrame(writeBuf *bytes.Buffer, f Frame)
- func Dial(network, address string, opts ...Option) (conn net.Conn, err error)
- func GetFactories() []string
- func GetSessionExpiry(conn net.Conn) (time.Time, bool)
- func Listen(network, address string, opts ...Option) (net.Listener, error)
- func RegisterFactory(scheme string, factory Factory)
- func UnregisterFactory(scheme string)
- type AcceptError
- type AdaptivePoll
- type BootstrapTokenIssuer
- type BufferLimits
- type Buffers
- type Config
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) CloseWrite() error
- func (c *Conn) GetMetrics() Metrics
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) MTU() int
- func (c *Conn) Read(p []byte) (n int, err error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SessionExpiry() (time.Time, bool)
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) Write(p []byte) (int, error)
- type DefaultMetrics
- func (m *DefaultMetrics) GetBytesReceived() int64
- func (m *DefaultMetrics) GetBytesSent() int64
- func (m *DefaultMetrics) GetDeleteTransactionCount() int64
- func (m *DefaultMetrics) GetListTransactionCount() int64
- func (m *DefaultMetrics) GetReadTransactionCount() int64
- func (m *DefaultMetrics) GetWriteTransactionCount() int64
- func (m *DefaultMetrics) IncrementBytesReceived(n int64)
- func (m *DefaultMetrics) IncrementBytesSent(n int64)
- func (m *DefaultMetrics) IncrementDeleteTransaction()
- func (m *DefaultMetrics) IncrementListTransaction()
- func (m *DefaultMetrics) IncrementReadTransaction()
- func (m *DefaultMetrics) IncrementWriteTransaction()
- func (m *DefaultMetrics) RecordRequest(a RequestAttempt)
- func (m *DefaultMetrics) RequestCounts() map[RequestAttempt]int64
- type Driver
- type Endpoint
- type Factory
- type Frame
- type Handshake
- type Listener
- func (l *Listener) Accept() (net.Conn, error)
- func (l *Listener) Addr() net.Addr
- func (l *Listener) CleanupBootstrap(ctx context.Context) error
- func (l *Listener) Close() error
- func (l *Listener) ConnectionString() (string, error)
- func (l *Listener) ConnectionStringFor(duration time.Duration) (string, error)
- type Metrics
- type Noise
- func (nh *Noise) DecryptData(dst, ciphertext []byte) ([]byte, error)
- func (nh *Noise) EncryptData(dst, plaintext []byte) ([]byte, error)
- func (nh *Noise) GetCipherStates() (send, recv *noise.CipherState, err error)
- func (nh *Noise) IsComplete() bool
- func (nh *Noise) IsInitiator() bool
- func (nh *Noise) ReadMessage(msg []byte) ([]byte, error)
- func (nh *Noise) SealData(dst, plaintext []byte) ([]byte, error)
- func (nh *Noise) UnsealData(dst, data []byte, maxChunk int) (plaintext, remaining []byte, err error)
- func (nh *Noise) WriteMessage(payload []byte) ([]byte, error)
- type Option
- func WithAcceptPoll(d time.Duration) Option
- func WithBufferLimits(limits BufferLimits) Option
- func WithConnectTimeout(d time.Duration) Option
- func WithContext(ctx context.Context) Option
- func WithDataPoll(d time.Duration) Option
- func WithEndpoints(handshake, token string) Option
- func WithFastPoll(d time.Duration) Option
- func WithIdleTimeout(d time.Duration) Option
- func WithMetrics(metrics Metrics) Option
- func WithPing(d time.Duration) Option
- func WithPrefixes(reqPrefix, resPrefix string) Option
- func WithProxy(address string, auth ProxyAuth, user, pass string) Option
- func WithProxyFunc(fn ProxyFunc) Option
- func WithProxyLog(logf func(format string, args ...any)) Option
- func WithSASExpiry(d time.Duration) Option
- func WithSessionDuration(d time.Duration) Option
- type ProxyAuth
- type ProxyConfig
- type ProxyDialer
- type ProxyFunc
- type RequestAttempt
- type RequestMetrics
- type Rotator
- type ServiceAddr
- type SessionTokens
- type Transport
Constants ¶
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 )
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 )
const FrameHeaderSize = 4 + 1 // 4 bytes length + 1 byte type
const MaxBlobBlockSize = 4 * 1024 * 1024
MaxBlobBlockSize is the maximum size of a single block in an Append Blob (4 MB).
const MaxBlocksPerBlob = 50000
MaxBlocksPerBlob is the maximum number of blocks per append blob.
const MaxQueueTextMessageSize = 64 * 1024
MaxQueuePayload is the maximum raw data size stored in a queue message (64 KB).
const MaxTableBinaryPropertySize = 64 * 1024
MaxTableBinaryPropertySize is the maximum size (64 KiB) for a single Edm.Binary property.
const MaxTableEntitySize = MaxTableProperties * MaxTableBinaryPropertySize
const MaxTableProperties = 15
MaxTableProperties is the number of binary properties we use to store a single large entity.
const NoiseOverhead = 4 + 16
NoiseOverhead is the encryption overhead: 4 bytes length prefix + 16 bytes AES-GCM tag.
Variables ¶
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") )
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") )
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.
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.
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.
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 ¶
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 ¶
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 ¶
GetSessionExpiry reads the optional connection capability without requiring callers to inspect credentials. Non-aznet connections can implement it too.
func Listen ¶
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 ¶
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 ¶
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.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn implements net.Conn.
func (*Conn) Close ¶
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 ¶
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 (*Conn) MTU ¶
MTU returns the maximum number of application bytes that can fit in a single transport frame for the current connection.
func (*Conn) RemoteAddr ¶
func (*Conn) SessionExpiry ¶
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) Write ¶
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 ¶
Endpoint represents an aznet endpoint.
func NewEndpoint ¶
NewEndpoint creates a new Endpoint from a URL.
func (*Endpoint) BuildConnURL ¶
BuildConnURL constructs the final aznet connection URL with base64 encoded SAS tokens.
func (*Endpoint) JoinURL ¶
JoinURL joins the base service URL with a resource name and optional SAS token.
func (*Endpoint) ParseSAS ¶
ParseSAS parses the handshake and token SAS tokens from the URL query. It returns the decoded SAS strings (without leading '?').
func (*Endpoint) ServiceURL ¶
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 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) CleanupBootstrap ¶
CleanupBootstrap removes the shared discovery namespace. Call only after all users of that namespace have stopped. It is deliberately independent of Close.
func (*Listener) ConnectionString ¶
ConnectionString returns bootstrap credentials for this listener.
func (*Listener) ConnectionStringFor ¶
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 ¶
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 ¶
NewNoiseClient creates a new Noise Protocol handshake as the initiator (client). It uses the NN pattern (no static keys, anonymous connection).
func NewNoiseServer ¶
NewNoiseServer creates a new Noise Protocol handshake as the responder (server). It uses the NN pattern (no static keys, anonymous connection).
func (*Noise) DecryptData ¶
DecryptData decrypts application data using the established session cipher.
func (*Noise) EncryptData ¶
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 ¶
IsComplete returns true if the handshake is complete and session keys are established.
func (*Noise) IsInitiator ¶
IsInitiator returns true if the handshake is the initiator.
func (*Noise) ReadMessage ¶
ReadMessage processes a handshake message from the peer, decrypting the payload. It returns the decrypted payload.
func (*Noise) SealData ¶
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.
type Option ¶
type Option func(*Config)
Option defines a functional option for Listen/Dial.
func WithAcceptPoll ¶
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 ¶
WithConnectTimeout bounds client setup and the lifetime of Queue tokens issued by a listener. Zero or negative values leave the default unchanged.
func WithContext ¶
WithContext sets the base context for all network/SDK calls initiated by Listen/Dial. Useful for cancellation or shared tracing.
func WithDataPoll ¶
WithDataPoll sets how often established connections poll for data.
func WithEndpoints ¶
WithEndpoints allows overriding the default handshake and token endpoints used during the connection bootstrap phase.
func WithFastPoll ¶
WithFastPoll sets the polling interval used when data is actively flowing.
func WithIdleTimeout ¶
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 ¶
WithMetrics sets a custom metrics implementation for tracking connection statistics. If not provided, a default implementation with atomic counters will be used.
func WithPrefixes ¶
WithPrefixes sets the prefixes that drivers use when creating per-connection request/response artefacts (e.g. blobs or queues).
func WithProxy ¶
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 ¶
WithProxyFunc is WithProxy with the proxy chosen per connection.
func WithProxyLog ¶
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 ¶
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 ¶
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 )
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 ¶
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 ¶
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 ¶
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.
Source Files
¶
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). |
