productfiles

Private files for host applications

productfiles exposes the native private-file operations that Starmap uses. Starport can use these operations without copying filesystem access code. The package does no catalog acquisition and starts no background work.

The host selects its absolute paths through productpaths or explicit settings. NewDirectory creates missing private directories and validates existing access. ExistingDirectory validates an existing directory without creating paths. Neither operation repairs existing permissions. Child checks or creates a private child directory. CreateChild requires a new child and refuses an existing path.

directory, err := productfiles.NewDirectory(configDirectory)
if err != nil {
    return err
}
// A nil previous value requires an absent file.
return directory.CompareAndPublish(ctx, "config.env", nil, configBytes)

Each directory binding retains its original filesystem identity. The Identity method exposes the native volume and directory identity for host recovery records. The FileIdentity function reads the native identity of a caller-owned open file or directory. It does not establish an access policy for that handle.

An operation refuses a replaced directory, an unsafe ancestor, or invalid native access. Linux and macOS use ownership, modes, and the applicable ACL checks. Windows uses the native owner and DACL checks. New files have private access from creation.

ReadFile requires a byte limit and reads one regular private file. CopyFile streams one regular private file into a caller-owned writer under an explicit byte limit. It checks native access and identity before and after the copy and supports context cancellation. The caller must discard partial output after an error, fence writers, and verify content hashes when required. Streaming does not create a snapshot or approve recovery.

CompareAndPublish requires matching previous bytes before it replaces a file. A nil previous value means absence. An empty, non-nil value means an empty file. CompareAndRemove also requires matching bytes and allows retries after removal.

Record publication reserves .record-publications for its writer lock and recovery receipts. Writes and recovery preserve unknown entries and changed files. RecoverPublications recovers abandoned record writes under the same lock. It does not recover an application transaction across config, data, or state roots. Record writes have a 64 MiB bound.

An errors.PublicationError means the change became visible, but durability remains unconfirmed. The caller must retain the intended bytes and resolve that result before a different write. It must not assume that the old file remains selected.

Open returns a checked os.Root that the caller must close. Raw operations on that root follow the standard library contract. They do not inherit the record publication or recovery contract.

PublishDirectory moves a direct child between open roots on the same filesystem. It refuses any existing destination, including an empty directory. The caller must sync staged contents before the move and both parent directories afterward. The caller also owns recovery if its operation spans multiple roots. SyncDirectory reports native synchronization errors without claiming hardware power-loss qualification.

CheckNoPendingPublications inspects existing publication journals without creating files or recovering writes. It uses the existing native writer lock and refuses pending journals. PublicationDirectoryName identifies metadata owned by this package. Hosts must preserve that metadata and fence writers before copying inspected state.

InspectRetainedPublications validates captured publication evidence without filesystem operations. The caller supplies verified file sizes and digests, a bounded reader, and a destination owner check. The result selects journals and matching staging files for inactive retention. The caller must preserve those bytes and validate all remaining destination records separately. Historical native identities cannot authorize cleanup on a restore host. This check never promotes staged bytes or approves application permission.