Documentation
¶
Overview ¶
Package dmsgasync pkg/dmsg/dmsgasync/client.go c1-net-dmsg
Package dmsgasync pkg/dmsg/dmsgasync/discovery.go c1-net-dmsg
Package dmsgasync pkg/dmsg/dmsgasync/dmsgasync.go c1-net-dmsg
Store and forward for offline dmsg keys. A recipient chooses inbox hosts, signs a Record naming them and registers with each. A sender that cannot reach the recipient deposits a payload on one of its hosts, and the recipient fetches it when it comes back. The host applies the recipient's sender Policy to the sender key the dmsg stream authenticates. See docs/design/dmsg-async.md.
Package dmsgasync pkg/dmsg/dmsgasync/host.go c1-net-dmsg
Package dmsgasync pkg/dmsg/dmsgasync/record.go c1-net-dmsg
Package dmsgasync pkg/dmsg/dmsgasync/store.go c1-net-dmsg
Index ¶
- Constants
- Variables
- func Ack(ctx context.Context, dial Dialer, host cipher.PubKey, ids []string) (int, error)
- func Deposit(ctx context.Context, dial Dialer, host, to cipher.PubKey, port uint16, ...) (string, error)
- func DepositAny(ctx context.Context, dial Dialer, rec Record, port uint16, ref string, ...) (cipher.PubKey, error)
- func Fetch(ctx context.Context, dial Dialer, host cipher.PubKey, ports []uint16, ...) (int, error)
- func NewRef() string
- func PublishRecord(ctx context.Context, hc *http.Client, discURL string, rec Record) error
- func Register(ctx context.Context, dial Dialer, host cipher.PubKey, rec Record, pol Policy) error
- func RemotePK(conn net.Conn) (cipher.PubKey, bool)
- func Unregister(ctx context.Context, dial Dialer, host cipher.PubKey) (int, error)
- type Dialer
- type Handler
- type Header
- type Host
- type HostConfig
- type Limits
- type Message
- type Policy
- type Record
- func FetchRecord(ctx context.Context, hc *http.Client, discURL string, pk cipher.PubKey) (Record, error)
- func LookupRecord(ctx context.Context, dial Dialer, host, pk cipher.PubKey) (Record, error)
- func NewRecord(pk cipher.PubKey, sk cipher.SecKey, hosts []cipher.PubKey, maxMessage int, ...) (Record, error)
- type Stats
Constants ¶
const ( DefaultMaxMessage = 64 << 10 DefaultMaxPerRecipient = 200 DefaultMaxRecipientBytes = 8 << 20 DefaultMaxPerSender = 20 DefaultMaxTotal = 256 << 20 DefaultTTL = 7 * 24 * time.Hour // MaxMessageLimit caps any message size, since a fetch reply carries at // least one whole message. MaxMessageLimit = 1 << 20 // MaxRecordHosts bounds the hosts one Record may name. MaxRecordHosts = 4 // MaxRecordLifetime bounds how far ahead a Record may expire. MaxRecordLifetime = 30 * 24 * time.Hour )
Defaults for a zero field in Limits.
const ( OpRegister = "register" OpUnregister = "unregister" OpRecord = "record" OpDeposit = "deposit" OpFetch = "fetch" OpAck = "ack" )
Operations a client sends.
const ( StoreDisk = "disk" StoreMemory = "memory" )
Store backends.
const Port = skyenv.DmsgAsyncPort
Port is the dmsg port inbox hosts serve.
Variables ¶
var ( ErrNotHosted = errors.New("dmsg-async: host does not hold messages for this key") ErrNotAllowed = errors.New("dmsg-async: the recipient does not accept messages from this sender") ErrTooBig = errors.New("dmsg-async: message is larger than the host takes") ErrRecipientFull = errors.New("dmsg-async: the recipient has too much waiting on this host") ErrSenderFull = errors.New("dmsg-async: this sender has too much waiting for the recipient") ErrStoreFull = errors.New("dmsg-async: host store is full") ErrBadRecord = errors.New("dmsg-async: invalid inbox record") ErrBadRequest = errors.New("dmsg-async: malformed request") ErrInternal = errors.New("dmsg-async: host error") )
Errors an operation can end with. The host sends a code and the client maps it back to one of these.
var ErrNoRecord = errors.New("dmsg-async: no inbox record")
ErrNoRecord means dmsg discovery has no inbox record for the key.
Functions ¶
func Ack ¶
Ack removes the dialer's messages that ids name from host and reports how many it removed.
func Deposit ¶
func Deposit(ctx context.Context, dial Dialer, host, to cipher.PubKey, port uint16, ref string, payload []byte) (string, error)
Deposit leaves payload for `to` on port with host and returns its id.
func DepositAny ¶
func DepositAny(ctx context.Context, dial Dialer, rec Record, port uint16, ref string, payload []byte) (cipher.PubKey, error)
DepositAny deposits on rec's hosts in order until one takes it, and returns that host. It fails with the last error when none does.
func Fetch ¶
func Fetch(ctx context.Context, dial Dialer, host cipher.PubKey, ports []uint16, handle Handler) (int, error)
Fetch takes what waits for the dialer on host for ports, hands each message to handle and acks the ones it took. It repeats while the host has more and reports how many were handled.
func NewRef ¶
func NewRef() string
NewRef returns a fresh deposit reference. A sender reuses one ref for every retry of the same message so a host stores it once.
func PublishRecord ¶
PublishRecord posts rec to the dmsg discovery at discURL.
func Register ¶
Register registers rec and pol with host. rec MUST be signed by the dialer's own key and name host.
Types ¶
type Handler ¶
Handler takes one fetched message. A nil error acks it. An error leaves it on the host for a later fetch.
type Header ¶
type Header struct {
ID string `json:"id"`
From cipher.PubKey `json:"from"`
Port uint16 `json:"port"`
Size int `json:"size"`
Deposited time.Time `json:"deposited"`
}
Header describes one stored message.
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host serves the dmsg-async protocol for the keys registered with it.
func NewHost ¶
func NewHost(cfg HostConfig) (*Host, error)
NewHost opens the store and loads the registrations a disk host kept.
func (*Host) Handle ¶
Handle runs one operation from remote on conn and closes it. remote MUST be the key the stream authenticated.
func (*Host) Registered ¶
Registered lists the keys registered with this host.
type HostConfig ¶
type HostConfig struct {
// PK is the host's own key, which a record must name.
PK cipher.PubKey
// Store is StoreDisk (the default) or StoreMemory.
Store string
// Dir holds the disk store and the registrations. Required for StoreDisk.
Dir string
Limits Limits
// Accepts reports whether this host agrees to hold for a key. It is
// asked when the key registers, and a key it refuses cannot register.
Accepts func(cipher.PubKey) bool
Log *logging.Logger
}
HostConfig configures an inbox host.
type Limits ¶
type Limits struct {
MaxMessage int `json:"max_message,omitempty"`
MaxPerRecipient int `json:"max_per_recipient,omitempty"`
MaxRecipientBytes int64 `json:"max_recipient_bytes,omitempty"`
MaxTotal int64 `json:"max_total_size,omitempty"`
TTL time.Duration `json:"ttl,omitempty"`
}
Limits bounds a host's store. A zero field takes its default.
func (Limits) WithDefaults ¶
WithDefaults returns l with each zero field at its default.
type Message ¶
type Message struct {
Header
Payload []byte
// Host is the inbox host that held it.
Host cipher.PubKey
}
Message is a fetched message.
type Policy ¶
type Policy struct {
// Allow lists the senders that may deposit. Empty allows every key.
Allow []cipher.PubKey `json:"allow,omitempty"`
// Deny lists senders that may never deposit.
Deny []cipher.PubKey `json:"deny,omitempty"`
// MaxPerSender bounds what one sender may have waiting. Zero takes
// DefaultMaxPerSender.
MaxPerSender int `json:"max_per_sender,omitempty"`
// PortAllow narrows who may deposit on the ports it names: only the listed
// senders, and only when Allow and Deny let them.
PortAllow map[uint16][]cipher.PubKey `json:"port_allow,omitempty"`
}
Policy is the recipient's rule for who may deposit. Only its hosts see it.
type Record ¶
type Record struct {
PK cipher.PubKey `json:"pk"`
Hosts []cipher.PubKey `json:"hosts"`
MaxMessage int `json:"max_message"`
Seq uint64 `json:"seq"`
Expires time.Time `json:"expires"`
Sig cipher.Sig `json:"sig"`
}
Record is a recipient's signed statement of where to deposit for it. It names hosts, not senders, so publishing it does not reveal its contacts.
func FetchRecord ¶
func FetchRecord(ctx context.Context, hc *http.Client, discURL string, pk cipher.PubKey) (Record, error)
FetchRecord reads pk's inbox record from the dmsg discovery at discURL and verifies it.
func LookupRecord ¶
LookupRecord asks host for pk's current record and verifies it.
func NewRecord ¶
func NewRecord(pk cipher.PubKey, sk cipher.SecKey, hosts []cipher.PubKey, maxMessage int, seq uint64, lifetime time.Duration) (Record, error)
NewRecord builds and signs a record for pk.
Source Files