linkpearl

package module
v0.0.0-...-9b61062 Latest Latest
Warning

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

 Go to latest Published: Jan 16, 2025 License: LGPL-3.0 Imports: 23 Imported by: 3

README

linkpearl

more about that name

A wrapper around mautrix-go with infrastructure/glue code included

How to get

go get github.com/etkecc/go-linkpearl

lp, err := linkpearl.New(&linkpearl.Config{
	// your options here
})
if err != nil {
	panic(err)
}

go lp.Start()

TODO

  • Unit tests

Features

  • Zero configuration End-to-End encryption
  • Zero configuration persistent storage
  • Zero configuration session restores
  • Zero configuration room and user account data encryption with AES GCM (both keys and values)
  • Zero configuration room and user account data caching
  • Threads support
  • All wrapped components exported

Documentation

Overview

Package linkpearl represents the library itself

Index

Constants

View Source 
const (
	// DefaultMaxRetries for operations like autojoin
	DefaultMaxRetries = 10
	// DefaultAccountDataCache size
	DefaultAccountDataCache = 1000
	// DefaultEventsLimit for methods like lp.Threads() and lp.FindEventBy()
	DefaultEventsLimit = 1000
	// DefaultTypingTimeout in seconds for typing notifications
	DefaultTypingTimeout = 60
	// DefaultUserAgent for HTTP requests
	DefaultUserAgent = "Linkpearl (library; +https://gitlab.com/etke.cc/linkpearl)"
)
View Source 
const (
	// MaxRetries is the maximum number of retries for sending a message
	MaxRetries = 5
	// DefaultTypingTimeout is the step delay for sending message retries
	RetryDelay = 5 * time.Second
)

Variables

View Source 
var ErrInvalidData = errors.New("invalid data")

ErrInvalidData returned in provided encrypted data (ciphertext) is invalid

Functions

func EventContains 

func EventContains[T comparable](evt *event.Event, field string, value T) bool

EventContains checks if raw event content contains specified field with specified values

func EventField 

func EventField[T comparable](content *event.Content, field string) T

EventField returns field value from raw event content

func EventParent 

func EventParent(currentID id.EventID, content event.Relatable) id.EventID

EventParent returns parent event ID (either from thread or from reply-to relation), like GetRelatesTo(), but with content and default return value

func EventRelatesTo 

func EventRelatesTo(evt *event.Event) *event.RelatesTo

EventRelatesTo uses evt as source for EventParent() and RelatesTo()

func GetParent 

func GetParent(evt *event.Event) id.EventID

GetParent is nil-safe version of evt.Content.AsMessage().RelatesTo.(GetThreadParent()|GetReplyTo())

func ParseContent 

func ParseContent(evt *event.Event, log *zerolog.Logger)

ParseContent parses event content according to evt.Type

func RelatesTo 

func RelatesTo(parentID id.EventID, noThreads ...bool) *event.RelatesTo

RelatesTo returns relation object of a matrix event (either threads with reply-to fallback or plain reply-to)

func UnwrapError 

func UnwrapError(err error) error

UnwrapError tries to unwrap a error into something meaningful, like mautrix.HTTPError or mautrix.RespError

Types

type Config 

type Config struct {
	// Homeserver url
	Homeserver string
	// Login is a localpart for password auth or full mxid for shared secret auth (honoroit - for password, @honoroit:example.com - for shared secret)
	Login string
	// Password for login/password auth only
	Password string
	// Shared secret for login/sharedsecret auth only
	SharedSecret string

	// JoinPermit is a callback function that tells
	// if linkpearl should respond to the given "invite" event
	// and join the room
	JoinPermit func(context.Context, *event.Event) bool

	// AutoLeave if true, linkpearl will automatically leave empty rooms
	AutoLeave bool

	// AccountDataCache size
	AccountDataCache int

	// AccountDataSecret (Password) for encryption
	AccountDataSecret string

	// MaxRetries for operations like auto join
	MaxRetries int

	// EventsLimit for methods like lp.Threads() or lp.FindEventBy()
	EventsLimit int

	// UserAgent for requests
	UserAgent string

	// Logger
	Logger zerolog.Logger

	// DB object
	DB *sql.DB
	// Dialect of the DB: postgres, sqlite3
	Dialect string
}

Config represents matrix config

func (*Config) LoginAs 

func (cfg *Config) LoginAs() *mautrix.ReqLogin

LoginAs for cryptohelper

type Crypter 

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

Crypter is special object that handles data encryption and decryption apart from Matrix' standard encryption. It can encrypt and decrypt arbitrary data using secret key (password)

func NewCrypter 

func NewCrypter(secretkey string) (*Crypter, error)

NewCrypter creates new Crypter

func (*Crypter) Decrypt 

func (c *Crypter) Decrypt(data string) (string, error)

Decrypt data

func (*Crypter) Encrypt 

func (c *Crypter) Encrypt(data string) (string, error)

Encrypt data

type Linkpearl 

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

Linkpearl object

func New 

func New(cfg *Config) (*Linkpearl, error)

New linkpearl

func (*Linkpearl) FindEventBy 

func (l *Linkpearl) FindEventBy(ctx context.Context, roomID id.RoomID, fieldValue map[string]string, fromToken ...string) *event.Event

FindEventBy tries to find message event by field and value

func (*Linkpearl) FindThreadBy 

func (l *Linkpearl) FindThreadBy(ctx context.Context, roomID id.RoomID, fieldValue map[string]string, fromToken ...string) *event.Event

FindThreadBy tries to find thread message event by field and value

func (*Linkpearl) GetAccountData 

func (l *Linkpearl) GetAccountData(ctx context.Context, name string) (map[string]string, error)

GetAccountData of the user (from cache and API, with encryption support)

func (*Linkpearl) GetAccountDataCrypter 

func (l *Linkpearl) GetAccountDataCrypter() *Crypter

GetAccountDataCrypter returns crypter used for account data (if any)

func (*Linkpearl) GetClient 

func (l *Linkpearl) GetClient() *mautrix.Client

GetClient returns underlying API client

func (*Linkpearl) GetDB 

func (l *Linkpearl) GetDB() *sql.DB

GetDB returns underlying DB object

func (*Linkpearl) GetMachine 

func (l *Linkpearl) GetMachine() *crypto.OlmMachine

GetMachine returns underlying OLM machine

func (*Linkpearl) GetRoomAccountData 

func (l *Linkpearl) GetRoomAccountData(ctx context.Context, roomID id.RoomID, name string) (map[string]string, error)

GetRoomAccountData of the room (from cache and API, with encryption support)

func (*Linkpearl) OnEvent 

func (l *Linkpearl) OnEvent(callback mautrix.EventHandler)

OnEvent shortcut to mautrix.DefaultSyncer.OnEvent

func (*Linkpearl) OnEventType 

func (l *Linkpearl) OnEventType(eventType event.Type, callback mautrix.EventHandler)

OnEventType allows callers to be notified when there are new events for the given event type. There are no duplicate checks.

func (*Linkpearl) OnSync 

func (l *Linkpearl) OnSync(callback mautrix.SyncHandler)

OnSync shortcut to mautrix.DefaultSyncer.OnSync

func (*Linkpearl) RedactReaction 

func (l *Linkpearl) RedactReaction(ctx context.Context, roomID id.RoomID, eventID id.EventID, reaction string) error

RedactReaction redacts a reaction from a message

func (*Linkpearl) Relations 

func (l *Linkpearl) Relations(ctx context.Context, roomID id.RoomID, eventID id.EventID, relType string, fromToken ...string) (*RespRelations, error)

Relations returns all relations of the given type for the given event

func (*Linkpearl) ReplaceReaction 

func (l *Linkpearl) ReplaceReaction(ctx context.Context, roomID id.RoomID, eventID id.EventID, oldReaction, newReaction string) error

ReplaceReaction replaces a reaction with another

func (*Linkpearl) Send 

func (l *Linkpearl) Send(ctx context.Context, roomID id.RoomID, content any) (id.EventID, error)

Send a message to the roomID and automatically try to encrypt it, if the destination room is encrypted

func (*Linkpearl) SendFile 

func (l *Linkpearl) SendFile(ctx context.Context, roomID id.RoomID, req *mautrix.ReqUploadMedia, msgtype event.MessageType, relates ...*event.RelatesTo) error

SendFile to a matrix room

func (*Linkpearl) SendMessageEvent 

func (l *Linkpearl) SendMessageEvent(ctx context.Context, roomID id.RoomID, eventType event.Type, contentJSON any, currentAttempt ...int) (resp *mautrix.RespSendEvent, err error)

SendMessageEvent sends a message event to the roomID and automatically retries if the server returns a 502 or 404 error

func (*Linkpearl) SendNotice 

func (l *Linkpearl) SendNotice(ctx context.Context, roomID id.RoomID, message string, relates ...*event.RelatesTo)

SendNotice to a room with optional relations, markdown supported

func (*Linkpearl) SendReaction 

func (l *Linkpearl) SendReaction(ctx context.Context, roomID id.RoomID, eventID id.EventID, reaction string) error

SendReaction sends a reaction to a message

func (*Linkpearl) SendTyping 

func (l *Linkpearl) SendTyping(ctx context.Context, roomID id.RoomID, typing bool, timeout ...int)

SendTyping notification

func (*Linkpearl) SetAccountData 

func (l *Linkpearl) SetAccountData(ctx context.Context, name string, data map[string]string) error

SetAccountData of the user (to cache and API, with encryption support)

func (*Linkpearl) SetJoinPermit 

func (l *Linkpearl) SetJoinPermit(value func(context.Context, *event.Event) bool)

SetJoinPermit sets the join permit callback function

func (*Linkpearl) SetRoomAccountData 

func (l *Linkpearl) SetRoomAccountData(ctx context.Context, roomID id.RoomID, name string, data map[string]string) error

SetRoomAccountData of the room (to cache and API, with encryption support)

func (*Linkpearl) Start 

func (l *Linkpearl) Start(ctx context.Context, optionalStatusMsg ...string) error

Start performs matrix /sync

func (*Linkpearl) Stop 

func (l *Linkpearl) Stop(ctx context.Context)

Stop the client

func (*Linkpearl) Threads 

func (l *Linkpearl) Threads(ctx context.Context, roomID id.RoomID, fromToken ...string) (*RespThreads, error)

Threads endpoint, ref: https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv1roomsroomidthreads

type ReqPresence 

type ReqPresence struct {
	Presence  event.Presence `json:"presence"`
	StatusMsg string         `json:"status_msg,omitempty"`
}

type RespRelations 

type RespRelations struct {
	Chunk     []*event.Event `json:"chunk"`
	NextBatch string         `json:"next_batch"`
}

RespRelations is response of https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv1roomsroomidrelationseventidreltype

type RespThreads 

type RespThreads struct {
	Chunk     []*event.Event `json:"chunk"`
	NextBatch string         `json:"next_batch"`
}

RespThreads is response of https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv1roomsroomidthreads

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.