Package com.tnsai.tools.file

Record Class FileGuardConfig

java.lang.Object

java.lang.Record

com.tnsai.tools.file.FileGuardConfig

Record Components:

maxReadBytes - upper bound on a single file read; rejected before I/O

maxWriteBytes - upper bound on a single file write; rejected before I/O

allowedExtensions - lowercased extensions (no leading dot); empty defers to toolkit default

sandboxRoot - absolute, normalized directory; every resolved path must start with it

public record FileGuardConfig(long maxReadBytes, long maxWriteBytes, Set<String> allowedExtensions, Path sandboxRoot)
extends Record

Declarative guardrail for every file-touching @Tool in tnsai-tools.

Holds the four invariants every file-aware toolkit needs to enforce:

1. Sandbox — paths must resolve under sandboxRoot; absolute paths to system files and ../ escapes are rejected.
2. Read cap — files larger than maxReadBytes are refused before any byte is read into the JVM heap.
3. Write cap — write payloads above maxWriteBytes are refused before disk I/O begins.
4. Extension whitelist — when non-empty, only files whose lowercased extension is in allowedExtensions are admitted; an empty set defers to the per-toolkit default supplied at the call site.

Resolution order is defaults() → env vars → compiled fallback. Programmatic per-tenant policy is expressed by passing a custom FileGuardConfig to a toolkit's (FileGuardConfig) constructor.

Field Summary

Fields

Modifier and Type	Field	Description
static final long	DEFAULT_MAX_READ_BYTES	10 MB read cap when neither env var nor explicit config overrides.
static final long	DEFAULT_MAX_WRITE_BYTES	1 MB write cap when neither env var nor explicit config overrides.
static final String	ENV_ALLOWED_EXTS	Env var: comma-separated extensions, no leading dot.
static final String	ENV_MAX_READ_BYTES	Env var: long, bytes.
static final String	ENV_MAX_WRITE_BYTES	Env var: long, bytes.
static final String	ENV_SANDBOX_ROOT	Env var: absolute directory path.

Constructor Summary

Constructors

Constructor	Description
FileGuardConfig(long maxReadBytes, long maxWriteBytes, Set<String> allowedExtensions, Path sandboxRoot)	Creates an instance of a FileGuardConfig record class.

Method Summary

Modifier and Type	Method	Description
Set<String>	allowedExtensions()	Returns the value of the allowedExtensions record component.
static FileGuardConfig	defaults()	Builds a config from environment variables, falling back to compiled defaults for any var that is unset or unparseable.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
final int	hashCode()	Returns a hash code value for this object.
long	maxReadBytes()	Returns the value of the maxReadBytes record component.
long	maxWriteBytes()	Returns the value of the maxWriteBytes record component.
Path	sandboxRoot()	Returns the value of the sandboxRoot record component.
final String	toString()	Returns a string representation of this record class.
FileGuardConfig	withAllowedExtensions(Set<String> extensions)	Returns a new config with the given allowed extensions, all other fields unchanged.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

DEFAULT_MAX_READ_BYTES

public static final long DEFAULT_MAX_READ_BYTES

10 MB read cap when neither env var nor explicit config overrides.

See Also:

• Constant Field Values

DEFAULT_MAX_WRITE_BYTES

public static final long DEFAULT_MAX_WRITE_BYTES

1 MB write cap when neither env var nor explicit config overrides.

See Also:

• Constant Field Values

ENV_MAX_READ_BYTES

public static final String ENV_MAX_READ_BYTES

Env var: long, bytes. Overrides DEFAULT_MAX_READ_BYTES.

See Also:

• Constant Field Values

ENV_MAX_WRITE_BYTES

public static final String ENV_MAX_WRITE_BYTES

Env var: long, bytes. Overrides DEFAULT_MAX_WRITE_BYTES.

See Also:

• Constant Field Values

ENV_ALLOWED_EXTS

public static final String ENV_ALLOWED_EXTS

Env var: comma-separated extensions, no leading dot.

See Also:

• Constant Field Values

ENV_SANDBOX_ROOT

public static final String ENV_SANDBOX_ROOT

Env var: absolute directory path. Defaults to the JVM CWD.

See Also:

• Constant Field Values

Constructor Details

FileGuardConfig

public FileGuardConfig(long maxReadBytes,
 long maxWriteBytes,
 Set<String> allowedExtensions,
 Path sandboxRoot)

Creates an instance of a FileGuardConfig record class.

Parameters:

maxReadBytes - the value for the maxReadBytes record component

maxWriteBytes - the value for the maxWriteBytes record component

allowedExtensions - the value for the allowedExtensions record component

sandboxRoot - the value for the sandboxRoot record component

Method Details

defaults

public static FileGuardConfig defaults()

Builds a config from environment variables, falling back to compiled defaults for any var that is unset or unparseable. Called once at toolkit instantiation via the no-arg constructor path.

The returned config has empty allowedExtensions unless ENV_ALLOWED_EXTS is set — empty defers to the per-toolkit default at call sites, which is the right behavior for a generic config.

Returns:

resolved configuration

withAllowedExtensions

public FileGuardConfig withAllowedExtensions(Set<String> extensions)

Returns a new config with the given allowed extensions, all other fields unchanged. Useful for toolkits that want to layer their own default on top of defaults().

Parameters:

extensions - new extension whitelist (may be empty)

Returns:

derived config

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

maxReadBytes

public long maxReadBytes()

Returns the value of the maxReadBytes record component.

Returns:

the value of the maxReadBytes record component

maxWriteBytes

public long maxWriteBytes()

Returns the value of the maxWriteBytes record component.

Returns:

the value of the maxWriteBytes record component

allowedExtensions

public Set<String> allowedExtensions()

Returns the value of the allowedExtensions record component.

Returns:

the value of the allowedExtensions record component

sandboxRoot

public Path sandboxRoot()

Returns the value of the sandboxRoot record component.

Returns:

the value of the sandboxRoot record component