Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
WithDirectAnnounce sets indexer URLs to send direct HTTP announcements to.