Documentation
¶
Overview ¶
Package download provides safe local file writes for OSF downloads, including conflict policies, path traversal protection, and folder-tree manifests.
Index ¶
- func NormalizeDestination(dest string) (string, error)
- func NormalizeRemotePath(remote string) (string, error)
- func ResolveDestination(destRoot, remote string) (string, error)
- func WriteStreamAtomically(dst string, src io.Reader, perm fs.FileMode, policy ConflictPolicy) (written bool, err error)
- type ConflictPolicy
- type FolderDownloadFile
- type FolderDownloadManifest
- type FolderDownloadPlan
- type FolderDownloadRecord
- type FolderDownloadStatus
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizeDestination ¶
NormalizeDestination cleans and resolves the user-selected destination directory to an absolute path. Returns an error if the path is empty or resolves to ".".
func NormalizeRemotePath ¶
NormalizeRemotePath cleans an OSF remote path into a relative forward-slash path. It collapses redundant segments and rejects directory traversal attempts ("..").
Example ¶
dst, _ := NormalizeRemotePath("/data//results.csv")
fmt.Println(dst)
Output: data/results.csv
func ResolveDestination ¶
ResolveDestination joins the normalized destination root and remote path safely. It validates that the resulting path stays within the destination root and follows symlinks to prevent directory traversal attacks.
func WriteStreamAtomically ¶
func WriteStreamAtomically(dst string, src io.Reader, perm fs.FileMode, policy ConflictPolicy) (written bool, err error)
WriteStreamAtomically writes a single file to dst through a temporary file. The temporary file is created alongside the destination and atomically renamed on success to prevent partial writes.
It returns written=false when the destination exists and ConflictSkip is used.
Types ¶
type ConflictPolicy ¶
type ConflictPolicy string
ConflictPolicy controls what happens when the local destination already exists.
const ( // ConflictFail stops the download when the destination exists. ConflictFail ConflictPolicy = "fail" // ConflictSkip leaves the destination untouched and reports a skipped write. ConflictSkip ConflictPolicy = "skip" // ConflictOverwrite replaces the existing destination after a successful stream. ConflictOverwrite ConflictPolicy = "overwrite" )
func ParseConflictPolicy ¶
func ParseConflictPolicy(value string) (ConflictPolicy, error)
ParseConflictPolicy converts text into a validated conflict policy.
Example ¶
policy, _ := ParseConflictPolicy("skip")
fmt.Println(policy)
Output: skip
func (ConflictPolicy) Validate ¶
func (p ConflictPolicy) Validate() error
Validate reports whether the policy is one of the supported values.
type FolderDownloadFile ¶
type FolderDownloadFile struct {
RemotePath string
Reader io.Reader
Open func() (io.ReadCloser, error)
KnownBytes *int64
}
FolderDownloadFile describes one remote file in a folder-tree download.
The file content can be supplied either as a reader or an opener. If the reader also implements io.Closer, it is closed after the write completes.
type FolderDownloadManifest ¶
type FolderDownloadManifest struct {
DestinationRoot string `json:"destinationRoot"`
ConflictPolicy ConflictPolicy `json:"conflictPolicy"`
Records []FolderDownloadRecord `json:"records"`
}
FolderDownloadManifest summarizes the result of a folder-tree download.
type FolderDownloadPlan ¶
type FolderDownloadPlan struct {
// contains filtered or unexported fields
}
FolderDownloadPlan validates and resolves folder-tree download entries.
func NewFolderDownloadPlan ¶
func NewFolderDownloadPlan(destRoot string, policy ConflictPolicy, files []FolderDownloadFile) (*FolderDownloadPlan, error)
NewFolderDownloadPlan builds a download plan for a folder tree.
func (*FolderDownloadPlan) Execute ¶
func (p *FolderDownloadPlan) Execute() (FolderDownloadManifest, error)
Execute downloads the planned folder tree and returns a manifest of the result.
type FolderDownloadRecord ¶
type FolderDownloadRecord struct {
RemotePath string `json:"remotePath"`
LocalPath string `json:"localPath"`
Bytes *int64 `json:"bytes,omitempty"`
Status FolderDownloadStatus `json:"status"`
Error string `json:"error,omitempty"`
}
FolderDownloadRecord is one entry in a folder download manifest.
type FolderDownloadStatus ¶
type FolderDownloadStatus string
FolderDownloadStatus describes the outcome for a folder download entry.
const ( // FolderDownloadWritten means the file was written successfully. FolderDownloadWritten FolderDownloadStatus = "written" // FolderDownloadSkipped means the local destination already existed and was left untouched. FolderDownloadSkipped FolderDownloadStatus = "skipped" // FolderDownloadFailed means the file could not be read or written. FolderDownloadFailed FolderDownloadStatus = "failed" )
Source Files