ZDDC/zddc/internal/zddc/file.go

package zddc

import (
	"os"

	"gopkg.in/yaml.v3"
)

// ACLRules holds email allow/deny lists.
type ACLRules struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}

// ZddcFile represents the parsed contents of a .zddc configuration file.
//
// Admins is honored only in the root .zddc file (<ZDDC_ROOT>/.zddc); subdir
// .zddc files have their Admins entry ignored by IsAdmin so that someone who
// can write into a subtree cannot grant themselves admin access. ACL on the
// other hand cascades — see EffectivePolicy / AllowedWithChain.
//
// Title is read only from per-project .zddc files (the file directly inside
// each project root) by ServeProjectList; it surfaces a human-readable name
// for the project on the landing-page picker. Optional — projects without a
// title fall back to displaying the directory name.
//
// Apps is a per-directory cascade override mapping app name → source spec.
// The spec is one of: "stable" / "beta" / "alpha" (channel on the canonical
// upstream), "v0.0.4" / "v0.0" / "v0" (version pin on the canonical
// upstream), an absolute "https://..." URL (custom mirror), or a relative
// or absolute filesystem path (./local.html, /opt/zddc/foo.html).
//
// On a request for a tool HTML, zddc-server walks .zddc files leaf→root
// looking for an Apps entry; first match wins. With no entry anywhere, the
// server serves the version baked into the binary at compile time (//go:embed).
// Fetched URL sources are cached in <ZDDC_ROOT>/_app/; the cache is fetch-once
// and never re-validates — operators delete the file to force a refetch.
type ZddcFile struct {
	ACL    ACLRules          `yaml:"acl"`
	Admins []string          `yaml:"admins"`
	Title  string            `yaml:"title"`
	Apps   map[string]string `yaml:"apps,omitempty"`
}

// ParseFile reads and parses a .zddc YAML file.
// Returns an empty ZddcFile (no rules) if the file does not exist.
func ParseFile(path string) (ZddcFile, error) {
	data, err := os.ReadFile(path)
	if os.IsNotExist(err) {
		return ZddcFile{}, nil
	}
	if err != nil {
		return ZddcFile{}, err
	}

	var zf ZddcFile
	if err := yaml.Unmarshal(data, &zf); err != nil {
		return ZddcFile{}, err
	}
	return zf, nil
}