Documentation
¶
Overview ¶
Package cloudstoragecommon holds helpers shared across the Cloud Storage tool implementations, chiefly error classification.
Index ¶
- Variables
- func ProcessGCSError(err error) util.ToolboxError
- func ResolveBool(cfgVal *bool, params map[string]any, key string) bool
- func ResolveString(cfgVal *string, params map[string]any, key string) string
- func ResolveSymlinks(path string) (string, error)
- func ResolveWithinDir(dir, rel string) (string, error)
- func ValidateLocalPath(p string) (string, error)
Constants ¶
This section is empty.
Variables ¶
var ErrBinaryContent = errors.New("cloud storage object is not valid UTF-8 text")
ErrBinaryContent is returned by the source when an object's bytes are not valid UTF-8. The MCP tool result channel only carries text today, so binary payloads cannot be faithfully round-tripped; ProcessGCSError maps this to an Agent error so the LLM knows to stop asking for this object.
TODO: when the toolbox supports non-text MCP content (embedded resources, images, blobs), remove this guard and return binary payloads directly.
var ErrDestinationExists = errors.New("download destination already exists")
ErrDestinationExists is returned by the download_object source method when the local destination file already exists and overwrite is false. ProcessGCSError maps this to an Agent error so the LLM can retry the call with overwrite=true.
var ErrReadSizeLimitExceeded = errors.New("cloud storage read size limit exceeded")
ErrReadSizeLimitExceeded is returned by the source when an object/range would exceed the source's configured byte limit. ProcessGCSError maps this to an Agent error because the LLM can fix the call by narrowing the 'range' parameter.
Functions ¶
func ProcessGCSError ¶
func ProcessGCSError(err error) util.ToolboxError
ProcessGCSError classifies an error from the Cloud Storage Go client into either an Agent Error (the LLM can self-correct by changing its input — bad request, missing bucket/object, unsatisfiable range) or a Server Error (infrastructure failure — auth, IAM denial, quota, 5xx, network cancellation). See DEVELOPER.md "Tool Invocation & Error Handling" for the wider rationale.
func ResolveBool ¶ added in v1.6.0
func ResolveString ¶ added in v1.6.0
func ResolveSymlinks ¶ added in v1.10.0
ResolveSymlinks returns the final filesystem target of path, following every symbolic link along the way. Comparing *this* against a configured boundary — rather than the caller-supplied name — is what stops a path that merely looks like it sits inside the boundary from opening a file outside it.
Paths whose trailing components do not exist yet (the normal case for a download destination) are resolved as deeply as the filesystem allows, and the missing components are appended literally.
A component that exists as a symbolic link but does not resolve — a dangling link — is rejected rather than treated as a missing name. Creating a file at such a path follows the link, so accepting it on the strength of its literal name would reopen the very escape this function exists to close.
The returned path reflects the filesystem as it was during the walk, so a caller that opens the path afterwards is still racing anyone able to write into the directories it traverses. Hard links are not detectable here at all. Both remain the operator's to contain with OS permissions.
func ResolveWithinDir ¶ added in v1.6.0
ResolveWithinDir joins rel onto dir and returns the result only if it stays inside dir, both as written and after symlinks are resolved. The returned path is the cleaned join, not the symlink-resolved target, so callers keep reporting the location the user asked for.
func ValidateLocalPath ¶
ValidateLocalPath enforces the local-filesystem path contract used by download_object and upload_object: non-empty, absolute after filepath.Clean, and free of ".." components. It returns the cleaned path. OS permissions remain the real isolation boundary; this check just prevents obvious traversal mistakes and forces callers to be explicit about where they want bytes to land. Confining a path to a configured directory is a separate concern; see ResolveWithinDir and ResolveSymlinks.
Types ¶
This section is empty.
Source Files