machine

package

v0.3.0 Latest Latest Go to latest Published: Oct 24, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/getsphericon/sphericon

Links

Open Source Insights

Documentation ¶

Overview ¶

Package machine tells an open or click made by software from one made by a person (ADR 0053, GLOSSARY: Machine engagement). A hit is machine when its user-agent belongs to a known crawler or scanner (the crawler-user-agents list, a maintained library) or its address lies inside an iCloud Private Relay egress range, a list Apple publishes and the refresh job keeps in a plain table. Detection is a partial signal: Apple publishes no list for Mail Privacy Protection and the Private Relay list is known to be incomplete. Neither the address nor the user-agent is kept: they are read for the verdict and dropped.

The table holds no Workspace data, so the package holds the raw ent client.

Index ¶

Constants
Variables
type Detector
- func New(client *ent.Client, source Source) *Detector
- func (d *Detector) IsMachine(ctx context.Context, userAgent, clientAddr string) bool
- func (d *Detector) Refresh(ctx context.Context) error
type HTTPSource
- func NewHTTPSource() HTTPSource
- func (s HTTPSource) Fetch(ctx context.Context) (io.ReadCloser, error)
type Source

Constants ¶

View Source

const RangesURL = "https://mask-api.icloud.com/egress-ip-ranges.csv"

RangesURL is where Apple publishes the Private Relay egress ranges, one CSV row per range (`172.224.224.0/31,GB,GB-LND,London,`).

Variables ¶

View Source

var ErrNoRanges = errors.New("machine: the published list holds no range")

ErrNoRanges is a published list that held no range: it never replaces the stored one.

Functions ¶

This section is empty.

Types ¶

type Detector ¶

type Detector struct {
	// contains filtered or unexported fields
}

Detector judges a hit and refreshes the ranges it judges by.

func New ¶

func New(client *ent.Client, source Source) *Detector

New builds the detector over the raw client and the source of the published list.

func (*Detector) IsMachine ¶

func (d *Detector) IsMachine(ctx context.Context, userAgent, clientAddr string) bool

IsMachine reports whether a hit with this user-agent from this client address is machine engagement. An unreadable address or an empty user-agent says nothing: only a positive match flags a hit, so a person is never discounted on a guess.

func (*Detector) Refresh ¶

func (d *Detector) Refresh(ctx context.Context) error

Refresh replaces the stored ranges with the published list. A failure of any kind, a fetch error, an unreadable or empty list or a failed write, leaves the old ranges in place.

type HTTPSource ¶

type HTTPSource struct {
	URL    string
	Client *http.Client
}

HTTPSource fetches the list from Apple over HTTPS.

func NewHTTPSource ¶

func NewHTTPSource() HTTPSource

NewHTTPSource is the source of the composition root: Apple's published URL.

func (HTTPSource) Fetch ¶

func (s HTTPSource) Fetch(ctx context.Context) (io.ReadCloser, error)

Fetch implements Source.

type Source ¶

type Source interface {
	Fetch(ctx context.Context) (io.ReadCloser, error)
}

Source fetches the published Private Relay list. It is the seam a test replaces so that no test reaches the network.

Source Files ¶

View all Source files

machine.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL