remote

README

remote

import "github.com/agentstation/starmap/pkg/catalogs/remote"

Package remote implements the versioned online Starmap-to-Starmap generation protocol and its verified client.

Index

• Constants
• func GenerationManifestPath(generationID string) string
• func ManifestETag(generationID string) string
• func MarshalManifest(manifest catalogs.GenerationManifest) ([]byte, error)
• func PayloadPath(generationID string) string
• type Client
  • func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)
  • func (c *Client) FetchCurrent(ctx context.Context) (catalogs.Generation, error)
  • func (c *Client) FetchCurrentIfChanged(ctx context.Context, generationID string) (generation catalogs.Generation, changed bool, err error)
  • func (c *Client) FetchGeneration(ctx context.Context, generationID string) (catalogs.Generation, error)
  • func (c *Client) OpenEventStream(ctx context.Context, lastEventID string) (*EventStream, error)
• type EventStream
  • func (s *EventStream) Close() error
  • func (s *EventStream) Next() (StreamEvent, error)
• type Publication
• type StreamEvent

Constants

const (
    // CatalogPath is appended to a versioned API base URL.
    CatalogPath = "/catalog"
    // ManifestPath returns the current strict generation manifest.
    ManifestPath = CatalogPath + "/manifest"
    // GenerationsPath prefixes immutable generation resource routes.
    GenerationsPath = CatalogPath + "/generations"
    // EventStreamPath returns post-commit catalog publication hints over SSE.
    EventStreamPath = "/updates/stream"
    // CatalogPublishedEvent is the sole catalog publication event name.
    CatalogPublishedEvent = "catalog.published"
    // ManifestMediaType identifies strict generation-manifest JSON.
    ManifestMediaType = "application/vnd.agentstation.starmap.catalog-manifest+json"
)

const (
    // EventStreamMediaType identifies the catalog publication SSE stream.
    EventStreamMediaType = "text/event-stream"
)

func GenerationManifestPath

func GenerationManifestPath(generationID string) string

GenerationManifestPath returns the immutable manifest route for generationID.

func ManifestETag

func ManifestETag(generationID string) string

ManifestETag returns the strong entity tag for a generation manifest. A generation ID is immutable and restricted to HTTP entity-tag-safe bytes.

func MarshalManifest

func MarshalManifest(manifest catalogs.GenerationManifest) ([]byte, error)

MarshalManifest returns strict JSON bytes for the server route.

func PayloadPath

func PayloadPath(generationID string) string

PayloadPath returns the immutable canonical payload route for generationID.

type Client

Client fetches one exact current generation from a versioned Starmap API.

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

func NewClient

func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)

NewClient creates a remote generation client. baseURL is the trusted, versioned HTTPS API root, for example https://starmap.example.com/api/v1. Plain HTTP is accepted only on loopback. The supplied HTTP client may add authentication or stricter TLS policy, but HTTPS responses must retain a standard verified certificate chain.

func (*Client) FetchCurrent

func (c *Client) FetchCurrent(ctx context.Context) (catalogs.Generation, error)

FetchCurrent fetches the current manifest followed by its immutable, generation-addressed payload and validates their binding and compatibility.

func (*Client) FetchCurrentIfChanged

func (c *Client) FetchCurrentIfChanged(ctx context.Context, generationID string) (generation catalogs.Generation, changed bool, err error)

FetchCurrentIfChanged conditionally fetches the current manifest relative to generationID. It returns changed=false without fetching a payload when the publisher reports that generationID is still current.

func (*Client) FetchGeneration

func (c *Client) FetchGeneration(ctx context.Context, generationID string) (catalogs.Generation, error)

FetchGeneration fetches and verifies one immutable generation by ID.

func (*Client) OpenEventStream

func (c *Client) OpenEventStream(ctx context.Context, lastEventID string) (*EventStream, error)

OpenEventStream opens the publication stream. lastEventID is sent as the standard Last-Event-ID request header when nonempty.

type EventStream

EventStream is one caller-owned catalog publication stream.

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

func (*EventStream) Close

func (s *EventStream) Close() error

Close closes the underlying response body and unblocks Next.

func (*EventStream) Next

func (s *EventStream) Next() (StreamEvent, error)

Next returns the next complete publication or comment activity frame.

type Publication

Publication identifies one committed immutable catalog generation.

type Publication struct {
    GenerationID string `json:"generation_id"`
    Sequence     uint64 `json:"sequence"`
}

type StreamEvent

StreamEvent is one parsed SSE publication or comment activity frame. Comments establish transport activity but never contain publication data.

type StreamEvent struct {
    Publication *Publication
    Comment     string
    EventID     string
}

Generated by gomarkdoc

Documentation

Overview

Package remote implements the versioned online Starmap-to-Starmap generation protocol and its verified client.

Index

• Constants
• func GenerationManifestPath(generationID string) string
• func ManifestETag(generationID string) string
• func MarshalManifest(manifest catalogs.GenerationManifest) ([]byte, error)
• func PayloadPath(generationID string) string
• type Client
  • func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)
  • func (c *Client) FetchCurrent(ctx context.Context) (catalogs.Generation, error)
  • func (c *Client) FetchCurrentIfChanged(ctx context.Context, generationID string) (generation catalogs.Generation, changed bool, err error)
  • func (c *Client) FetchGeneration(ctx context.Context, generationID string) (catalogs.Generation, error)
  • func (c *Client) OpenEventStream(ctx context.Context, lastEventID string) (*EventStream, error)
• type EventStream
  • func (s *EventStream) Close() error
  • func (s *EventStream) Next() (StreamEvent, error)
• type Publication
• type StreamEvent

Constants

const (
	// CatalogPath is appended to a versioned API base URL.
	CatalogPath = "/catalog"
	// ManifestPath returns the current strict generation manifest.
	ManifestPath = CatalogPath + "/manifest"
	// GenerationsPath prefixes immutable generation resource routes.
	GenerationsPath = CatalogPath + "/generations"
	// EventStreamPath returns post-commit catalog publication hints over SSE.
	EventStreamPath = "/updates/stream"
	// CatalogPublishedEvent is the sole catalog publication event name.
	CatalogPublishedEvent = "catalog.published"
	// ManifestMediaType identifies strict generation-manifest JSON.
	ManifestMediaType = "application/vnd.agentstation.starmap.catalog-manifest+json"
)

const (
	// EventStreamMediaType identifies the catalog publication SSE stream.
	EventStreamMediaType = "text/event-stream"
)

Functions

func GenerationManifestPath

func GenerationManifestPath(generationID string) string

GenerationManifestPath returns the immutable manifest route for generationID.

func ManifestETag

func ManifestETag(generationID string) string

ManifestETag returns the strong entity tag for a generation manifest. A generation ID is immutable and restricted to HTTP entity-tag-safe bytes.

func MarshalManifest

func MarshalManifest(manifest catalogs.GenerationManifest) ([]byte, error)

MarshalManifest returns strict JSON bytes for the server route.

func PayloadPath

func PayloadPath(generationID string) string

PayloadPath returns the immutable canonical payload route for generationID.

Types

type Client

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

Client fetches one exact current generation from a versioned Starmap API.

func NewClient

func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)

NewClient creates a remote generation client. baseURL is the trusted, versioned HTTPS API root, for example https://starmap.example.com/api/v1. Plain HTTP is accepted only on loopback. The supplied HTTP client may add authentication or stricter TLS policy, but HTTPS responses must retain a standard verified certificate chain.

func (*Client) FetchCurrent

func (c *Client) FetchCurrent(ctx context.Context) (catalogs.Generation, error)

FetchCurrent fetches the current manifest followed by its immutable, generation-addressed payload and validates their binding and compatibility.

func (*Client) FetchCurrentIfChanged

func (c *Client) FetchCurrentIfChanged(
	ctx context.Context,
	generationID string,
) (generation catalogs.Generation, changed bool, err error)

FetchCurrentIfChanged conditionally fetches the current manifest relative to generationID. It returns changed=false without fetching a payload when the publisher reports that generationID is still current.

func (*Client) FetchGeneration

func (c *Client) FetchGeneration(ctx context.Context, generationID string) (catalogs.Generation, error)

FetchGeneration fetches and verifies one immutable generation by ID.

func (*Client) OpenEventStream

func (c *Client) OpenEventStream(
	ctx context.Context,
	lastEventID string,
) (*EventStream, error)

OpenEventStream opens the publication stream. lastEventID is sent as the standard Last-Event-ID request header when nonempty.

type EventStream

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

EventStream is one caller-owned catalog publication stream.

func (*EventStream) Close

func (s *EventStream) Close() error

Close closes the underlying response body and unblocks Next.

func (*EventStream) Next

func (s *EventStream) Next() (StreamEvent, error)

Next returns the next complete publication or comment activity frame.

type Publication

type Publication struct {
	GenerationID string `json:"generation_id"`
	Sequence     uint64 `json:"sequence"`
}

Publication identifies one committed immutable catalog generation.

type StreamEvent

type StreamEvent struct {
	Publication *Publication
	Comment     string
	EventID     string
}

StreamEvent is one parsed SSE publication or comment activity frame. Comments establish transport activity but never contain publication data.