v3

Documentation

Overview

Package v3 defines data types for v3 of the formulae.brew.sh JSON API and some utility functions for working with the data.

Index

• Constants
• type Bottle
• type BottleFile
• type Cask
• type CaskArtifact
• type Conflicts
• type Dependencies
• type DependencyConfig
• type Formula
• type MacOSBounds
• type ProcessType
• type Requirement
• type Response
• type Service
  • func (s *Service) RunArgs(os string) ([]string, error)
• type ServiceRunType
• type Signature
• type Tap
• type URLSpec
• type Variation

Constants

const (
	ProcessTypeInteractive = "interactive" // value for interactive process
	ProcessTypeBackground  = "background"  // value for background process
)

Types

type Bottle

type Bottle struct {
	Rebuild int                              `json:"rebuild"`
	RootURL string                           `json:"root_url"`
	Files   map[platform.Platform]BottleFile `json:"files"`
}

Bottle represents the bottle section.

type BottleFile

type BottleFile struct {
	Cellar string `json:"cellar"`
	Sha256 string `json:"sha256"`
}

BottleFile defines a bottle.files entry.

type Cask

type Cask struct {
	Token            string             `json:"token"`
	Name             string             `json:"name"`
	Description      string             `json:"desc"`
	Homepage         string             `json:"homepage"`
	URL              string             `json:"url"`
	Version          string             `json:"version"`
	Sha256           string             `json:"sha256"`
	Artifacts        []CaskArtifact     `json:"artifacts"`
	RubySourcePath   string             `json:"ruby_source_path"`
	RubySourceSHA256 string             `json:"ruby_source_sha256"`
	URLSpecs         map[string]URLSpec `json:"url_specs,omitempty"`
	DependsOn        struct {
		MacOS map[string][]string `json:"macos"`
	} `json:"depends_on"`
}

Cask represents a cask's metadata.

type CaskArtifact

type CaskArtifact map[string][]any

CaskArtifact represents an artifact stanza defined by a cask.

https://docs.brew.sh/Cask-Cookbook#stanza-descriptions

type Conflicts

type Conflicts struct {
	ConflictsWith        []string `json:"conflicts_with,omitempty"`
	ConflictsWithReasons []string `json:"conflicts_with_reasons,omitempty"`
}

Conflicts specifies formula conflicts.

type Dependencies

type Dependencies map[string]*DependencyConfig

Dependencies represents a collection of dependencies.

type DependencyConfig

type DependencyConfig struct {
	Tags          []string     `json:"tags,omitempty"`
	UsesFromMacOS *MacOSBounds `json:"uses_from_macos,omitempty"`
}

DependencyConfig provides additional context for a dependency.

type Formula

type Formula struct {
	Desc     string `json:"desc"`
	License  string `json:"license"`
	Homepage string `json:"homepage"`
	URLs     map[string]struct {
		URL      string `json:"url"`
		Revision string `json:"revision,omitempty"`
		Tag      string `json:"tag,omitempty"`
		Branch   string `json:"branch,omitempty"`
		Using    string `json:"using,omitempty"`
		Checksum string `json:"checksum,omitempty"`
	} `json:"urls"`
	PostInstallDefined bool                               `json:"post_install_defined"`
	RubySourcePath     string                             `json:"ruby_source_path"`
	RubySourceSHA256   string                             `json:"ruby_source_sha256"`
	LinkOverwrite      []string                           `json:"link_overwrite,omitempty"`
	Revision           int                                `json:"revision,omitempty"`
	KegOnlyReason      brewv1.KegOnlyConfig               `json:"keg_only_reason,omitempty"`
	PourBottleOnlyIf   string                             `json:"pour_bottle_only_if,omitempty"`
	Caveats            string                             `json:"caveats,omitempty"`
	Service            Service                            `json:"service,omitempty"`
	VersionScheme      int                                `json:"version_scheme,omitempty"`
	Version            string                             `json:"version"`
	Bottle             Bottle                             `json:"bottle"`
	VersionedFormulae  []string                           `json:"versioned_formulae,omitempty"`
	DeprecationDate    string                             `json:"deprecation_date,omitempty"`
	DeprecationReason  string                             `json:"deprecation_reason,omitempty"`
	DisabledDate       string                             `json:"disable_date,omitempty"`
	DisabledReason     string                             `json:"disable_reason,omitempty"`
	Dependencies       Dependencies                       `json:"dependencies,omitempty"`
	HeadDependencies   Dependencies                       `json:"head_dependencies,omitempty"`
	Requirements       []Requirement                      `json:"requirements,omitempty"`
	Variations         map[platform.Platform]Dependencies `json:"variations,omitempty"`
	Conflicts          Conflicts                          `json:",inline"`
}

Formula represents a formula's metadata.

type MacOSBounds

type MacOSBounds struct {
	Since string `json:"since,omitempty"`
}

MacOSBounds constrains a macOS dependency.

type ProcessType

type ProcessType string

ProcessType represents a service's process type.

type Requirement

type Requirement struct {
	Name     string   `json:"name"`
	Cask     any      `json:"cask"`
	Download any      `json:"download"`
	Version  *string  `json:"version"`
	Contexts []string `json:"contexts"`
	Specs    []string `json:"specs"`
}

Requirement represents a requirement.

type Response

type Response struct {
	// Payload is the requested tap's information
	Payload Tap `json:"payload"`

	// Signatures is a list of JSON Web Signatures that can be used to verify the payload
	Signatures []Signature `json:"signatures"`
}

Response represents the v3 API's response format.

type Service

type Service struct {
	// Specifies per-OS service name
	// 2 examples: xinit, dbus
	// Both only specify a name for "macos"
	Name map[string]string `json:"name,omitempty"`

	// Run specifies the command to run
	//
	// One of three options:
	// - string: single argument (60 examples)
	// - []string: list of args (234 examples)
	// - map[string][]string: map OS to list of args (3 examples)
	//
	// Parse as any, require furthing parsing if needed
	Run any `json:"run"`

	RunType              ServiceRunType    `json:"run_type"`
	EnvironmentVariables map[string]string `json:"environment_variables,omitempty"`
	Interval             time.Duration     `json:"interval,omitempty"`
	Cron                 string            `json:"cron,omitempty"`
	RequireRoot          bool              `json:"require_root,omitempty"`
	KeepAlive            struct {
		Always         bool `json:"always,omitempty"`
		SuccessfulExit bool `json:"successful_exit,omitempty"`
		Crashed        bool `json:"crashed,omitempty"` // 1 example
	} `json:"keep_alive,omitempty"`
	WorkingDir string `json:"working_dir,omitempty"`

	// 2 examples: knot-resolver, knot
	InputPath string `json:"input_path,omitempty"`

	LogPath string `json:"log_path,omitempty"`

	ErrorLogPath string `json:"error_log_path,omitempty"`

	// 3 examples: bitlbee, launch_socket_server, launchdns
	Sockets string `json:"sockets,omitempty"`

	// 4 examples
	// seen: background|interactive
	ProcessType ProcessType `json:"process_type,omitempty"`

	// 1 example: gitlab-runner
	MacOSLegacyTimers bool `json:"macos_legacy_timers,omitempty"`
}

Service represents the service block.

https://docs.brew.sh/Formula-Cookbook#service-block-methods

func (*Service) RunArgs

func (s *Service) RunArgs(os string) ([]string, error)

RunArgs evaluates the command arguments to run The run field is a dynamic type so it needs extra parsing.

type ServiceRunType

type ServiceRunType string

ServiceRunType represents a run type for a service.

const (
	RunTypeImmediate ServiceRunType = "immediate" // immediate run type
	RunTypeInterval  ServiceRunType = "interval"  // interval run type
	RunTypeCron      ServiceRunType = "cron"      // cron run type
)

type Signature

type Signature struct {
	Protected string            `json:"protected"`
	Header    map[string]string `json:"header"`
	Signature string            `json:"signature"`
}

Signature represents the signature field.

type Tap

type Tap struct {
	TapGitHead    string             `json:"tap_git_head"`
	Aliases       map[string]string  `json:"aliases"`
	Renames       map[string]string  `json:"renames"`
	TapMigrations map[string]string  `json:"tap_migrations"`
	Formulae      map[string]Formula `json:"formulae,omitempty"`
	Casks         map[string]Cask    `json:"casks,omitempty"`
}

Tap represents a tap's metadata.

type URLSpec

type URLSpec struct {
	Verified  string            `json:"verified,omitempty"`
	Using     string            `json:"using,omitempty"`   // one of "post" or "homebrew_curl"
	Cookies   map[string]string `json:"cookies,omitempty"` // 4 examples
	Referer   string            `json:"referer,omitempty"`
	Header    any               `json:"header,omitempty"`     // string or array of strings
	UserAgent string            `json:"user_agent,omitempty"` // 37 examples
	Data      map[string]string `json:"data,omitempty"`       // 2 examples: segger-jlink, segger-ozone
}

URLSpec the url_specs entry.

type Variation

type Variation struct {
	// v3 caveats can only be set to a string that overwrites the general caveats.
	Caveats          string        `json:"caveats,omitempty"`
	Dependencies     Dependencies  `json:"dependencies,omitempty"`
	HeadDependencies Dependencies  `json:"head_dependencies,omitempty"`
	Requirements     []Requirement `json:"requirements,omitempty"`
	Conflicts        Conflicts     `json:",inline"`
}

Variation represents a platform-specific variation to the formula's metadata.