# Infra Protocol

Local protocols for personal infrastructure, currently including Infra Discovery for publishing and locating service endpoints.

## Metadata

- HTML: https://glenzli.com/en/projects/infra-protocol/
- Markdown: https://glenzli.com/en/projects/infra-protocol.md
- Collection: Projects
- Language: en
- Published: 2026-08-11
- Updated: 2026-08-27
- Status: active
- Tags: personal-infra, protocol, discovery, local-services

## Content

Infra Protocol maintains local protocols for personal infrastructure services. Its first protocol is **Infra Discovery**: a service publishes the protocol versions, bindings, and endpoints it offers, and a compatible consumer connects to the selected endpoint directly.

Discovery ends there. Requests, responses, errors, and authorization remain part of the selected application protocol.

  ![Services publish endpoints for compatible consumers to discover and select](/images/projects/infra-protocol-banner.webp)

## Infra Discovery

Each service publishes a registration manifest containing its stable identity, the current process `generation`, and a set of `(protocol, protocol_versions, binding, endpoint)` offers.

```text
Service -> registration manifest
Consumer -> exact protocol version + binding
Consumer ---------------------------> endpoint
```

    **Exact matching**
    A consumer selects an endpoint by an explicitly supported protocol version and binding.

    **Candidate endpoints**
    A manifest supplies candidate endpoints. Consumers confirm current state by connecting and may rescan after a failure.

    **Generation changes**
    A restart or offer change creates a new generation, published atomically after the endpoint is ready.

    **Current-user boundary**
    Manifests are owner-only. Unix socket and Windows named pipe providers must also verify that the peer belongs to the same OS user.

## Runtime directory

macOS, Linux, and Windows each have a current-user default. Sandboxed or packaged applications must use a shared directory that every participant can access. Discovery is unavailable when no such directory exists.

Unix socket endpoints are relative to the runtime directory and remain subject to platform path-length limits. Publishers and consumers both validate the final path and access boundary.

## Scope

The Infra Discovery schema ends at the endpoint. Requests, authorization, health state, and Console links belong to the selected application protocol. The repository contains the specification, JSON Schema, accepted and rejected fixtures, and conformance checks that go beyond the schema.

The current document version is `infra.discovery.registration@20260812.1`.