lock

type AccessMode int

type BreakCallbacks interface {
	// OnOpLockBreak is called when an oplock/lease must be broken.
	//
	// Parameters:
	//   - handleKey: The file handle key for the affected file
	//   - lock: The lock whose oplock must be broken
	//   - breakToState: The target lease state after break (e.g., LeaseStateRead or LeaseStateNone)
	OnOpLockBreak(handleKey string, lock *UnifiedLock, breakToState uint32)

	// OnByteRangeRevoke is called when a byte-range lock must be revoked
	// due to a cross-protocol conflict.
	//
	// Parameters:
	//   - handleKey: The file handle key for the affected file
	//   - lock: The byte-range lock that conflicts
	//   - reason: Human-readable reason for the revocation
	OnByteRangeRevoke(handleKey string, lock *UnifiedLock, reason string)

	// OnAccessConflict is called when an SMB access mode conflict is detected.
	//
	// Parameters:
	//   - handleKey: The file handle key for the affected file
	//   - existingLock: The lock holding the conflicting access mode
	//   - requestedMode: The access mode that was requested
	OnAccessConflict(handleKey string, existingLock *UnifiedLock, requestedMode AccessMode)
}

type ClientRegistration struct {
	// ClientID is the unique client identifier.
	ClientID string

	// AdapterType identifies which protocol adapter (e.g., "nfs", "smb").
	AdapterType string

	// TTL is how long to keep locks after disconnect (0 = immediate release).
	TTL time.Duration

	// RegisteredAt is when the client registered.
	RegisteredAt time.Time

	// LastSeen is the last activity timestamp.
	LastSeen time.Time

	// RemoteAddr is the client IP address (for logging/metrics).
	RemoteAddr string

	// LockCount is the number of locks held by this client.
	LockCount int

	// MonName is the monitored hostname (mon_id.mon_name from SM_MON).
	// This is typically the server's hostname that the client is monitoring.
	MonName string

	// Priv is the 16-byte private data returned in SM_NOTIFY callbacks.
	// Stored from SM_MON and sent back to the client when state changes.
	Priv [16]byte

	// SMState is the client's NSM state counter at registration time.
	// Used to detect stale registrations after client restarts.
	SMState int32

	// CallbackInfo contains RPC callback details from SM_MON my_id field.
	// Used to send SM_NOTIFY callbacks when server restarts or client crashes.
	CallbackInfo *NSMCallback
}

type ClientRegistrationStore interface {
	// PutClientRegistration stores or updates a client registration.
	// If a registration with the same ClientID exists, it is replaced.
	PutClientRegistration(ctx context.Context, reg *PersistedClientRegistration) error

	// GetClientRegistration retrieves a registration by client ID.
	// Returns nil, nil if the registration does not exist.
	GetClientRegistration(ctx context.Context, clientID string) (*PersistedClientRegistration, error)

	// DeleteClientRegistration removes a registration.
	// Returns nil if the registration does not exist.
	DeleteClientRegistration(ctx context.Context, clientID string) error

	// ListClientRegistrations returns all stored registrations.
	// Used on server startup to send SM_NOTIFY callbacks.
	ListClientRegistrations(ctx context.Context) ([]*PersistedClientRegistration, error)

	// DeleteAllClientRegistrations removes all registrations.
	// Used for SM_UNMON_ALL to clear all monitoring for a client.
	// Returns the count of deleted registrations.
	DeleteAllClientRegistrations(ctx context.Context) (int, error)

	// DeleteClientRegistrationsByMonName removes all registrations monitoring a specific host.
	// Used when a monitored host is known to have crashed.
	// Returns the count of deleted registrations.
	DeleteClientRegistrationsByMonName(ctx context.Context, monName string) (int, error)
}

type Config struct {
	// MaxLocksPerFile is the maximum number of locks allowed on a single file.
	// Prevents a single file from exhausting lock table resources.
	// Default: 1000
	MaxLocksPerFile int `mapstructure:"max_locks_per_file" yaml:"max_locks_per_file"`

	// MaxLocksPerClient is the maximum number of locks a single client can hold.
	// Prevents a single client from exhausting lock table resources.
	// Default: 10000
	MaxLocksPerClient int `mapstructure:"max_locks_per_client" yaml:"max_locks_per_client"`

	// MaxTotalLocks is the maximum total locks across all files and clients.
	// Provides a hard ceiling on lock manager memory usage.
	// Default: 100000
	MaxTotalLocks int `mapstructure:"max_total_locks" yaml:"max_total_locks"`

	// BlockingTimeout is the server-side timeout for blocking lock requests.
	// After this duration, the server will return NLM_LCK_DENIED_NOLOCKS or
	// similar to the client. The client may retry.
	// Default: 60s
	BlockingTimeout time.Duration `mapstructure:"blocking_timeout" yaml:"blocking_timeout"`

	// GracePeriodDuration is the duration of the grace period after server restart.
	// During this time, only lock reclaims are allowed (new locks are denied).
	// Default: 90s (NFS spec recommends 90 seconds minimum)
	GracePeriodDuration time.Duration `mapstructure:"grace_period" yaml:"grace_period"`

	// MandatoryLocking controls whether locks are mandatory or advisory.
	// - false (default): Advisory locks - the lock manager tracks locks but
	//   I/O operations are not blocked by locks (only lock operations check locks)
	// - true: Mandatory locks - I/O operations check and are blocked by locks
	// Advisory locking is more common and has better performance.
	// Default: false
	MandatoryLocking bool `mapstructure:"mandatory_locking" yaml:"mandatory_locking"`
}

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

type ConnectionTrackerConfig struct {
	// MaxConnectionsPerAdapter limits connections by adapter type.
	MaxConnectionsPerAdapter map[string]int

	// DefaultMaxConnections is the fallback limit (default: 10000).
	DefaultMaxConnections int

	// StaleCheckInterval is how often to check for stale clients (default: 30s).
	StaleCheckInterval time.Duration

	// OnClientDisconnect is called when a client is fully disconnected.
	OnClientDisconnect func(clientID string)
}

type FileHandle string

type FileLock struct {
	// ID is the lock identifier from the client.
	// For SMB2: derived from lock request (often 0 for simple locks)
	// For NLM: opaque client-provided lock handle
	ID uint64

	// SessionID identifies who holds the lock.
	// For SMB2: SessionID from SMB header
	// For NLM: hash of network address + client PID
	SessionID uint64

	// Offset is the starting byte offset of the lock.
	Offset uint64

	// Length is the number of bytes locked.
	// 0 means "to end of file" (unbounded).
	Length uint64

	// Exclusive indicates lock type.
	// true = exclusive (write lock, blocks all other locks)
	// false = shared (read lock, allows other shared locks)
	Exclusive bool

	// AcquiredAt is the time the lock was acquired.
	AcquiredAt time.Time

	// ClientAddr is the network address of the client holding the lock.
	// Used for debugging and logging.
	ClientAddr string
}

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

type GraceState int

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

type LockConflict struct {
	// Offset is the starting byte offset of the conflicting lock.
	Offset uint64

	// Length is the number of bytes of the conflicting lock.
	Length uint64

	// Exclusive indicates type of conflicting lock.
	Exclusive bool

	// OwnerSessionID identifies the client holding the conflicting lock.
	OwnerSessionID uint64
}

type LockManager interface {

	// AddUnifiedLock adds a unified lock (byte-range or oplock).
	// Returns error if the lock conflicts with existing locks.
	AddUnifiedLock(handleKey string, lock *UnifiedLock) error

	// RemoveUnifiedLock removes a unified lock using POSIX splitting semantics.
	RemoveUnifiedLock(handleKey string, owner LockOwner, offset, length uint64) error

	// ListUnifiedLocks returns all unified locks on a file.
	ListUnifiedLocks(handleKey string) []*UnifiedLock

	// RemoveFileUnifiedLocks removes all unified locks for a file.
	RemoveFileUnifiedLocks(handleKey string)

	// UpgradeLock atomically converts a shared lock to exclusive if no other readers exist.
	UpgradeLock(handleKey string, owner LockOwner, offset, length uint64) (*UnifiedLock, error)

	// GetUnifiedLock retrieves a specific unified lock by owner and range.
	GetUnifiedLock(handleKey string, owner LockOwner, offset, length uint64) (*UnifiedLock, error)

	// CheckAndBreakOpLocksForWrite checks and breaks oplocks that conflict with a write.
	// Write breaks all Write oplocks to None, Read oplocks to None.
	// excludeOwner can be nil to check all owners.
	CheckAndBreakOpLocksForWrite(handleKey string, excludeOwner *LockOwner) error

	// CheckAndBreakOpLocksForRead checks and breaks oplocks that conflict with a read.
	// Read only breaks Write oplocks (to Read).
	// excludeOwner can be nil to check all owners.
	CheckAndBreakOpLocksForRead(handleKey string, excludeOwner *LockOwner) error

	// CheckAndBreakOpLocksForDelete checks and breaks all oplocks on a file.
	// Delete breaks all oplocks to None.
	// excludeOwner can be nil to check all owners.
	CheckAndBreakOpLocksForDelete(handleKey string, excludeOwner *LockOwner) error

	// Lock attempts to acquire a byte-range lock on a file.
	Lock(handleKey string, lock FileLock) error

	// Unlock releases a specific byte-range lock.
	Unlock(handleKey string, sessionID uint64, offset, length uint64) error

	// TestLock checks if a lock would succeed without acquiring it.
	TestLock(handleKey string, lock FileLock) (*LockConflict, error)

	// ListLocks returns all active byte-range locks on a file.
	ListLocks(handleKey string) []FileLock

	// EnterGracePeriod transitions to grace period state.
	EnterGracePeriod(expectedClients []string)

	// ExitGracePeriod manually exits the grace period.
	ExitGracePeriod()

	// IsOperationAllowed checks if a lock operation is allowed in the current state.
	IsOperationAllowed(op Operation) (bool, error)

	// MarkReclaimed records that a client has reclaimed their locks.
	MarkReclaimed(clientID string)

	// IsInGracePeriod returns true if grace period is currently active.
	IsInGracePeriod() bool

	// RegisterBreakCallbacks registers typed callbacks for break notifications.
	RegisterBreakCallbacks(callbacks BreakCallbacks)

	// RemoveAllLocks removes all locks (both legacy and unified) for a file.
	RemoveAllLocks(handleKey string)

	// RemoveClientLocks removes all locks held by a specific client.
	RemoveClientLocks(clientID string)

	// GetStats returns current lock manager statistics.
	GetStats() ManagerStats
}

type LockOwner struct {
	// OwnerID is the protocol-provided owner identifier.
	// Format: "{protocol}:{details}" - treated as OPAQUE by lock manager.
	// The lock manager never parses this string; it only compares for equality.
	OwnerID string

	// ClientID is the connection tracker client ID.
	// Used to clean up locks when a client disconnects.
	ClientID string

	// ShareName is the share this lock belongs to.
	// Used for per-share lock tracking and cleanup.
	ShareName string
}

type LockQuery struct {
	// FileID filters by file (string representation of FileHandle).
	// Empty string means no file filtering.
	FileID string

	// OwnerID filters by lock owner.
	// Empty string means no owner filtering.
	OwnerID string

	// ClientID filters by client.
	// Empty string means no client filtering.
	ClientID string

	// ShareName filters by share.
	// Empty string means no share filtering.
	ShareName string

	// IsLease filters by lock type.
	// nil means no type filtering (both leases and byte-range locks).
	// true means leases only.
	// false means byte-range locks only.
	IsLease *bool
}

type LockResult struct {
	// Success indicates whether the lock was acquired.
	Success bool

	// Lock is the acquired lock (nil if !Success).
	Lock *UnifiedLock

	// Conflict is the conflicting lock information (nil if Success).
	Conflict *UnifiedLockConflict

	// ShouldWait indicates whether the caller should wait and retry.
	// True when a blocking request found a conflict.
	ShouldWait bool

	// WaitFor is the list of owner IDs to wait for (for deadlock detection).
	WaitFor []string
}

type LockStore interface {

	// PutLock persists a lock. Overwrites if lock with same ID exists.
	PutLock(ctx context.Context, lock *PersistedLock) error

	// GetLock retrieves a lock by ID.
	// Returns ErrLockNotFound if lock doesn't exist.
	GetLock(ctx context.Context, lockID string) (*PersistedLock, error)

	// DeleteLock removes a lock by ID.
	// Returns ErrLockNotFound if lock doesn't exist.
	DeleteLock(ctx context.Context, lockID string) error

	// ListLocks returns locks matching the query.
	// Empty query returns all locks.
	ListLocks(ctx context.Context, query LockQuery) ([]*PersistedLock, error)

	// DeleteLocksByClient removes all locks for a client.
	// Returns number of locks deleted.
	// Used when a client disconnects to clean up its locks.
	DeleteLocksByClient(ctx context.Context, clientID string) (int, error)

	// DeleteLocksByFile removes all locks for a file.
	// Returns number of locks deleted.
	// Used when a file is deleted.
	DeleteLocksByFile(ctx context.Context, fileID string) (int, error)

	// GetServerEpoch returns current server epoch.
	// Returns 0 for a fresh server (never started).
	GetServerEpoch(ctx context.Context) (uint64, error)

	// IncrementServerEpoch increments and returns new epoch.
	// Called during server startup to detect restarts.
	// Locks with epoch < current epoch are stale.
	IncrementServerEpoch(ctx context.Context) (uint64, error)

	// ReclaimLease reclaims an existing lease during grace period.
	// This validates the lease existed in persistent storage before restart
	// and allows the client to re-establish the lease state.
	//
	// Parameters:
	//   - ctx: Context for cancellation
	//   - fileHandle: File handle for the lease
	//   - leaseKey: The 16-byte SMB lease key
	//   - clientID: Client identifier for ownership verification
	//
	// Returns:
	//   - *UnifiedLock: The reclaimed lease on success
	//   - error: ErrLockNotFound if lease doesn't exist
	ReclaimLease(ctx context.Context, fileHandle FileHandle, leaseKey [16]byte, clientID string) (*UnifiedLock, error)
}

type LockType int

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

type ManagerStats struct {
	// TotalLegacyLocks is the total number of legacy byte-range locks.
	TotalLegacyLocks int

	// TotalUnifiedLocks is the total number of unified locks.
	TotalUnifiedLocks int

	// TotalFiles is the number of files with any locks.
	TotalFiles int

	// BreakCallbackCount is the number of registered break callbacks.
	BreakCallbackCount int

	// GracePeriodActive indicates if grace period is active.
	GracePeriodActive bool
}

type NLMHolderInfo struct {
	// CallerName identifies the lock holder.
	// For SMB leases: "smb:<clientID>"
	// For NLM locks: Original caller_name from lock request
	CallerName string

	// Svid is the server-unique identifier (process ID in Unix terms).
	// For SMB leases: Always 0 (SMB has no process ID concept)
	// For NLM locks: Original svid from lock request
	Svid int32

	// OH is the owner handle (opaque identifier).
	// For SMB leases: First 8 bytes of the 128-bit LeaseKey
	// For NLM locks: Original oh from lock request
	OH []byte

	// Offset is the starting byte offset of the lock.
	// For SMB leases: Always 0 (whole file)
	// For NLM locks: Original offset from lock
	Offset uint64

	// Length is the number of bytes locked.
	// For SMB leases: ^uint64(0) (max value = whole file)
	// For NLM locks: Original length from lock
	Length uint64

	// Exclusive indicates if this is an exclusive (write) lock.
	// For SMB leases: true if lease has Write caching permission
	// For NLM locks: true if exclusive lock type
	Exclusive bool
}

type NSMCallback struct {
	// Hostname is the callback target (my_id.my_name).
	// This is where the SM_NOTIFY RPC will be sent.
	Hostname string

	// Program is the RPC program number (usually NLM 100021).
	Program uint32

	// Version is the program version.
	Version uint32

	// Proc is the procedure number for the callback.
	// NLM uses NLM_FREE_ALL (procedure 23) to release locks.
	Proc uint32
}

type OpLock struct {
	// LeaseKey is the 128-bit client-generated key identifying this lease.
	// Multiple file handles with the same key share the lease.
	LeaseKey [16]byte

	// LeaseState is the current lease state (R/W/H flags bitwise OR'd).
	// Use HasRead(), HasWrite(), HasHandle() to check individual flags.
	LeaseState uint32

	// BreakToState is the target state during an active break.
	// Zero if no break is in progress.
	BreakToState uint32

	// Breaking indicates a lease break is in progress awaiting acknowledgment.
	// When true, the client has been notified and must acknowledge.
	Breaking bool

	// Epoch is incremented on every lease state change (SMB3).
	// Used by clients to detect stale state notifications.
	Epoch uint16

	// BreakStarted records when the break was initiated.
	// Used to enforce break timeout (force revoke if client doesn't acknowledge).
	BreakStarted time.Time

	// Reclaim indicates this lease was reclaimed during grace period.
	// Set when SMB client reconnects after server restart and successfully
	// reclaims its previously held lease.
	Reclaim bool
}

type OpLockBreakCallback interface {
	// OnLeaseBreakTimeout is called when a lease break times out without acknowledgment.
	// The lease has already been force-revoked (deleted from store).
	OnLeaseBreakTimeout(leaseKey [16]byte)
}

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

type Operation struct {
	// IsReclaim indicates this is a lock reclaim during grace period.
	IsReclaim bool

	// IsTest indicates this is a lock test (query) operation.
	IsTest bool

	// IsNew indicates this is a new lock request (not reclaim or test).
	IsNew bool
}

type PersistedClientRegistration struct {
	// ClientID is the unique identifier (e.g., hostname or IP).
	ClientID string

	// MonName is the monitored hostname (from SM_MON mon_id.mon_name).
	// This identifies what host the client is monitoring.
	MonName string

	// Priv is the 16-byte private data for callbacks.
	// Returned unchanged in SM_NOTIFY to help client identify recovery context.
	Priv [16]byte

	// CallbackHost is the callback target hostname (from my_id.my_name).
	// This is where SM_NOTIFY RPCs will be sent.
	CallbackHost string

	// CallbackProg is the RPC program number for callbacks.
	// Typically NLM program number (100021).
	CallbackProg uint32

	// CallbackVers is the program version for callbacks.
	CallbackVers uint32

	// CallbackProc is the procedure number for callbacks.
	// NLM uses NLM_FREE_ALL (procedure 23) to release locks.
	CallbackProc uint32

	// RegisteredAt is when the registration was created.
	RegisteredAt time.Time

	// ServerEpoch is the server epoch at registration time.
	// Used to detect stale registrations from previous server instances.
	ServerEpoch uint64
}

type PersistedLock struct {
	// ID is the unique identifier for this lock (UUID).
	ID string `json:"id"`

	// ShareName is the share this lock belongs to.
	ShareName string `json:"share_name"`

	// FileID is the file identifier (string representation of FileHandle).
	FileID string `json:"file_id"`

	// OwnerID is the protocol-provided owner identifier.
	// Format: "{protocol}:{details}" - treated as opaque.
	OwnerID string `json:"owner_id"`

	// ClientID is the connection tracker client ID.
	// Used to clean up locks when a client disconnects.
	ClientID string `json:"client_id"`

	// LockType indicates shared (0) or exclusive (1).
	LockType int `json:"lock_type"`

	// Offset is the starting byte offset of the lock.
	Offset uint64 `json:"offset"`

	// Length is the number of bytes locked (0 = to EOF).
	Length uint64 `json:"length"`

	// AccessMode is the SMB share mode (0=none, 1=deny-read, 2=deny-write, 3=deny-all).
	AccessMode int `json:"share_reservation"`

	// AcquiredAt is when the lock was acquired.
	AcquiredAt time.Time `json:"acquired_at"`

	// ServerEpoch is the server epoch when the lock was acquired.
	// Used for split-brain detection and stale lock cleanup.
	ServerEpoch uint64 `json:"server_epoch"`

	// LeaseKey is the 128-bit client-generated key identifying the lease.
	// Non-empty (16 bytes) for leases, empty for byte-range locks.
	LeaseKey []byte `json:"lease_key,omitempty"`

	// LeaseState is the current R/W/H flags (LeaseStateRead|Write|Handle).
	// 0 for byte-range locks or None lease state.
	LeaseState uint32 `json:"lease_state,omitempty"`

	// LeaseEpoch is the SMB3 epoch counter, incremented on state change.
	// 0 for byte-range locks.
	LeaseEpoch uint16 `json:"lease_epoch,omitempty"`

	// BreakToState is the target state during an active lease break.
	// 0 if no break in progress.
	BreakToState uint32 `json:"break_to_state,omitempty"`

	// Breaking indicates a lease break is in progress awaiting acknowledgment.
	// False for byte-range locks.
	Breaking bool `json:"breaking,omitempty"`
}

type Stats struct {
	// TotalLocks is the total number of active locks
	TotalLocks int

	// UniqueFiles is the number of files with at least one lock
	UniqueFiles int

	// UniqueClients is the number of clients with at least one lock
	UniqueClients int

	// MaxLocksOnFile is the highest lock count on any single file
	MaxLocksOnFile int

	// MaxLocksForClient is the highest lock count for any single client
	MaxLocksForClient int
}

type UnifiedLock struct {
	// ID is a unique identifier for this lock (UUID).
	// Used for lock management, debugging, and metrics.
	ID string

	// Owner identifies who holds the lock.
	Owner LockOwner

	// FileHandle is the file this lock is on.
	// This is the store-specific file handle.
	FileHandle FileHandle

	// Offset is the starting byte offset of the lock.
	// For leases, this is always 0 (whole-file).
	Offset uint64

	// Length is the number of bytes locked.
	// 0 means "to end of file" (unbounded).
	// For leases, this is always 0 (whole-file).
	Length uint64

	// Type indicates whether this is a shared or exclusive lock.
	// For leases, this reflects the lease type:
	//   - LockTypeShared for Read-only leases
	//   - LockTypeExclusive for Write-containing leases
	Type LockType

	// AccessMode is the SMB share mode (NFS protocols ignore this).
	AccessMode AccessMode

	// AcquiredAt is when the lock was acquired.
	AcquiredAt time.Time

	// Blocking indicates whether this was a blocking (wait) request.
	// Non-blocking requests fail immediately on conflict.
	Blocking bool

	// Reclaim indicates whether this is a reclaim during grace period.
	// Reclaim locks have priority over new locks during grace period.
	Reclaim bool

	// Lease holds lease-specific state for SMB2/3 leases.
	// Nil for byte-range locks; non-nil for leases.
	// When non-nil, Offset=0 and Length=0 (whole-file).
	Lease *OpLock
}

type UnifiedLockConflict struct {
	// Lock is the conflicting lock.
	Lock *UnifiedLock

	// Reason describes why the conflict occurred.
	Reason string
}

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