publisher

package
v0.0.0-...-7d9dcd4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: Apache-2.0, MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrContextIDNotFound signals that no item is associated to the given
	// context ID.
	ErrContextIDNotFound = errors.New("context ID not found")

	// ErrAlreadyAdvertised signals that an advertisement for identical content
	// was already published.
	ErrAlreadyAdvertised = errors.New("advertisement already published")
)

Functions

func GenerateAd

func GenerateAd(ctx context.Context, publisherStore store.PublisherStore, peer peer.ID, addrs []multiaddr.Multiaddr, contextID []byte, md metadata.Metadata, isRm bool, mhs iter.Seq[mh.Multihash]) (schema.Advertisement, error)

GenerateAd generates an advertisement for the given parameters. Generation writes the store's mappings for the provider and context ID before it returns; should it fail partway, those writes are undone, so the store is as it was and the call can be retried. Any failure to undo is reported beside the cause.

Types

type AdvertSpec

type AdvertSpec struct {
	ContextID string
	Digests   iter.Seq[mh.Multihash]
	Metadata  metadata.Metadata
}

AdvertSpec is what one advertisement is generated from: the content it announces, the context ID it is published under and the metadata it carries.

type AdvertisementPublisher

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

func NewAdvertisementPublisher

func NewAdvertisementPublisher(id crypto.PrivKey, store store.PublisherStore, opts ...Option) (*AdvertisementPublisher, error)

func (*AdvertisementPublisher) AddToBatch

func (p *AdvertisementPublisher) AddToBatch(adv schema.Advertisement) error

AddToBatch queues an advertisement for the next Commit. Should that commit fail, the mappings from the advertisement's provider and context ID to its entries and to its metadata are dropped, so generating it again produces an advertisement rather than ErrAlreadyAdvertised. That is all an advertisement alone allows: a mapping it replaced is not recoverable, and a removal's generation deleted the mappings a retry would need, so a failed commit of a removal reports that. Publish and PublishBatch generate their advertisements themselves and queue them with an exact undo instead.

func (*AdvertisementPublisher) Commit

Commit publishes the pending advertisements under one new head and announces it. Should it fail, the store writes generating them made are undone, and any failure to undo is reported beside the commit's error: a mapping left behind would make its content unpublishable on retry, so the caller must know which ones could not be put back.

func (*AdvertisementPublisher) Discard

func (p *AdvertisementPublisher) Discard(ctx context.Context) error

Discard drops the pending advertisements without publishing them and undoes the store writes generating them made, so generating the same advertisements again produces them rather than ErrAlreadyAdvertised: what was pending lived only in memory, and a store that still called it advertised would make it unpublishable. It reports any undo that failed.

type AsyncPublisher

type AsyncPublisher interface {
	// Publish creates, signs and publishes an advert but does so asynchronously, so no advert CID is returned.
	Publish(ctx context.Context, provider peer.AddrInfo, contextID string, digests iter.Seq[mh.Multihash], meta metadata.Metadata) error
}

func AsyncFrom

func AsyncFrom(p Publisher) AsyncPublisher

type BatchPublisher

type BatchPublisher interface {
	// PublishBatch generates one advertisement per spec and publishes them
	// all under a single commit. See [IPNIPublisher.PublishBatch].
	PublishBatch(ctx context.Context, provider peer.AddrInfo, specs []AdvertSpec) (ipld.Link, error)
}

BatchPublisher publishes many advertisements under one commit.

type IPNIPublisher

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

func New

func New(id crypto.PrivKey, store store.PublisherStore, opts ...Option) (*IPNIPublisher, error)

New creates a new IPNI publisher. IPNIPublisher is not safe for concurrent use. There is the risk of losing advertisements if Publish is called from concurrent goroutines. If you will be publishing from multiple goroutines concurrently, a synchronization mechanism (such as sync.Mutex) must be used to ensure that Publish is called serially.

func (*IPNIPublisher) Publish

func (p *IPNIPublisher) Publish(ctx context.Context, providerInfo peer.AddrInfo, contextID string, digests iter.Seq[mh.Multihash], meta metadata.Metadata) (ipld.Link, error)

Publish creates a new advertisement from the latest head, signs it, and publishes it. Publish is not safe for concurrent use and advertisements may be lost if called concurrently. A mutex or any other synchronization mechanism must be used around Publish if it will be called from concurrent goroutines.

func (*IPNIPublisher) PublishBatch

func (p *IPNIPublisher) PublishBatch(ctx context.Context, provider peer.AddrInfo, specs []AdvertSpec) (ipld.Link, error)

PublishBatch generates one advertisement per spec and publishes them all under a single commit: one signed head and one announce however many specs there are, where Publish pays both per advertisement. A spec whose content is already advertised with identical metadata is skipped. The returned link is the head after the commit, unchanged when every spec was skipped and nil when nothing has ever been published.

PublishBatch reads the mappings of every spec with one call to the batch store, writes the adverts with one call, and writes the mappings and moves the head with one call (see WithBatchStore). On failure the store holds the mappings it held before the call, so calling again with the same specs publishes every one of them. With the default batch store, putting a mapping back can itself fail; the returned error then says which mappings could not be restored. Entries blocks and adverts are content addressed and are left in place. Like Publish, PublishBatch is not safe for concurrent use.

type Option

type Option func(cfg *options) error

Option is an option configuring a publisher.

func WithAnnounceAddrs

func WithAnnounceAddrs(addrs ...string) Option

WithAnnounceAddrs configures the multiaddrs that are put into announce messages to tell indexers the addresses to fetch advertisements from.

func WithBatchStore

func WithBatchStore(batchStore store.BatchStore) Option

WithBatchStore sets the store a batch is published through. Without it, a batch reads and writes its mappings one call at a time through the publisher's store, and writes back the mappings it changed when its commit fails. A store with transactions, or with calls that read and write many mappings at once, publishes a batch with fewer calls.

func WithDirectAnnounce

func WithDirectAnnounce(announceURLs ...string) Option

WithDirectAnnounce sets indexer URLs to send direct HTTP announcements to.

func WithTopic

func WithTopic(topic string) Option

type Publisher

type Publisher interface {
	// Publish creates, signs and publishes an advert. It then announces the new
	// advert to other indexers.
	Publish(ctx context.Context, provider peer.AddrInfo, contextID string, digests iter.Seq[mh.Multihash], meta metadata.Metadata) (ipld.Link, error)
}

Jump to

Keyboard shortcuts

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