broadcaster

README

go-broadcaster

Minimalist and opinionated package providing interfaces for "broadcasting" messages with zero or more images.

Documentation

Motivation

This package provides minimalist and opinionated interfaces for "broadcasting" simple messages with zero or more images.

A message consists of an optional title and body as well as zero or more images. How those elements are processed is left to service or target -specific implementations of the Broadcaster interfaces.

That's all it does and doesn't try to account for any other, or more complicated, publishing scenarios. There are other tools and packages for that.

This should still be considered "in flux"

Although the "skeleton" of this package and its interfaces is complete some details may still change. For example, it is expected that the Broadcaster interface will be updated to include a Close method shortly.

Example

Broadcasting a message

package broadcast

import (
	"context"
	"fmt"
	
	"github.com/aaronland/go-broadcaster"
)

func main() {

	ctx := context.Background()     

	br, _ := broadcaster.NewBroadcaster(ctx, "log://")

	msg := &broadcaster.Message{
		Title: "This is the title",
		Body:  "This is a message",
	}

	id, _ := br.BroadcastMessage(ctx, msg)

	fmt.Println(id.String())
	return nil
}

Error handling omitted for the sake of brevity.

Implementing the Broadcaster interface.

package broadcaster

import (
	"context"
	"github.com/aaronland/go-uid"
	"log"
	"time"
)

func init() {
	ctx := context.Background()
	RegisterBroadcaster(ctx, "log", NewLogBroadcaster)
}

// LogBroadcaster implements the `Broadcaster` interface to broadcast messages
type LogBroadcaster struct {
	Broadcaster
}

// NewLogBroadcaster returns a new `LogBroadcaster` configured by 'uri' which is expected to
// take the form of:
//
//	log://
//
// By default `LogBroadcaster` instances are configured to broadcast messages to a `log.Default`
// instance. If you want to change that call the `SetLogger` method.
func NewLogBroadcaster(ctx context.Context, uri string) (Broadcaster, error) {
	
	logger := log.Default()
	
	b := LogBroadcaster{}
	return &b, nil
}

// BroadcastMessage broadcast the title and body properties of 'msg' to the `log.Logger` instance
// associated with 'b'. It does not publish images yet. Maybe someday it will try to convert images
// to their ascii interpretations but today it does not. It returns the value of the Unix timestamp
// that the log message was broadcast.
func (b *LogBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error) {

	log_msg := fmt.Sprintf("%s %s", msg.Title, msg.Body)

	logger := slog.Default()	
	logger.Info(log_msg)

	now := time.Now()
	ts := now.Unix()

	return uid.NewInt64UID(ctx, ts)
}

UIDs

This package uses the aaronland/go-uid package to encapsulate unique identifiers returns by broadcasting targets.

Tools

$> make cli
go build -mod vendor -o bin/broadcast cmd/broadcast/main.go

broadcast

$> ./bin/broadcast -h
  -body string
    	The body of the message to broadcast.
  -broadcaster value
    	One or more aaronland/go-broadcast URIs.
  -image value
    	Zero or more paths to images to include with the message to broadcast.
  -title string
    	The title of the message to broadcast.
  -verbose
    	Enable verbose (debug) logging.	

For example:

$> ./bin/broadcast -broadcaster log:// -broadcaster null:// -body "hello world"
2022/11/08 08:44:47  hello world
NullUID# Int64UID#1667925887

Other implementations

flickr://

• https://github.com/aaronland/go-broadcaster-flickr

mastodon://

• https://github.com/aaronland/go-broadcaster-mastodon

slack://

• https://github.com/aaronland/go-broadcaster-slack

twitter://

• https://github.com/aaronland/go-broadcaster-twitter

This package is no longer maintained (and probably doesn't work anyway given all the changes to the Twitter API in recent years).

See also

• https://github.com/aaronland/go-uid

Documentation

Overview

Package broadcaster provided minimalist and opinionated methods for "broadcasting" messages with zero or more images.

Index

• func RegisterBroadcaster(ctx context.Context, scheme string, init_func BroadcasterInitializationFunc) error
• func Schemes() []string
• type Broadcaster
  • func NewBroadcaster(ctx context.Context, uri string) (Broadcaster, error)
  • func NewLogBroadcaster(ctx context.Context, uri string) (Broadcaster, error)
  • func NewMultiBroadcaster(ctx context.Context, broadcasters ...Broadcaster) (Broadcaster, error)
  • func NewMultiBroadcasterFromURIs(ctx context.Context, broadcaster_uris ...string) (Broadcaster, error)
  • func NewNullBroadcaster(ctx context.Context, uri string) (Broadcaster, error)
• type BroadcasterInitializationFunc
• type LogBroadcaster
  • func (b *LogBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)
• type Message
• type MultiBroadcaster
  • func (b *MultiBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)
• type NullBroadcaster
  • func (b *NullBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)

Functions

func RegisterBroadcaster

func RegisterBroadcaster(ctx context.Context, scheme string, init_func BroadcasterInitializationFunc) error

RegisterBroadcaster registers 'scheme' as a key pointing to 'init_func' in an internal lookup table used to create new `Broadcaster` instances by the `NewBroadcaster` method.

func Schemes

func Schemes() []string

Schemes returns the list of schemes that have been registered.

Types

type Broadcaster

type Broadcaster interface {
	// BroadcastMessage "broadcasts" a `Message` struct.
	BroadcastMessage(context.Context, *Message) (uid.UID, error)
}

Broadcaster provides a minimalist interface for "broadcasting" messages to an arbitrary service or target.

func NewBroadcaster

func NewBroadcaster(ctx context.Context, uri string) (Broadcaster, error)

NewBroadcaster returns a new `Broadcaster` instance configured by 'uri'. The value of 'uri' is parsed as a `url.URL` and its scheme is used as the key for a corresponding `BroadcasterInitializationFunc` function used to instantiate the new `Broadcaster`. It is assumed that the scheme (and initialization function) have been registered by the `RegisterBroadcaster` method.

func NewLogBroadcaster

func NewLogBroadcaster(ctx context.Context, uri string) (Broadcaster, error)

NewLogBroadcaster returns a new `LogBroadcaster` configured by 'uri' which is expected to take the form of:

log://?{PARAMETERS}

Where `{PARAMETERS}` may be one or more of the following: * ?ascii={BOOLEAN} – If true then ASCII-representations of each image in a message will be logged. Default is "false". By default `LogBroadcaster` instances are configured to broadcast messages to a `log/slog.Default` instance with an `INFO` level.

func NewMultiBroadcaster

func NewMultiBroadcaster(ctx context.Context, broadcasters ...Broadcaster) (Broadcaster, error)

func NewMultiBroadcasterFromURIs

func NewMultiBroadcasterFromURIs(ctx context.Context, broadcaster_uris ...string) (Broadcaster, error)

func NewNullBroadcaster

func NewNullBroadcaster(ctx context.Context, uri string) (Broadcaster, error)

type BroadcasterInitializationFunc

type BroadcasterInitializationFunc func(ctx context.Context, uri string) (Broadcaster, error)

BroadcasterInitializationFunc is a function defined by individual broadcaster package and used to create an instance of that broadcaster

type LogBroadcaster

type LogBroadcaster struct {
	Broadcaster
	// contains filtered or unexported fields
}

LogBroadcaster implements the `Broadcaster` interface to broadcast messages to a `log.Logger` instance.

func (*LogBroadcaster) BroadcastMessage

func (b *LogBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)

BroadcastMessage broadcast the title and body properties of 'msg' to the `log.Logger` instance associated with 'b'. If the `?ascii=` parameter in the constructor URI (see `NewLogBroadcaster`) is true then each image will be converted in to an ASCII representation and logged. It returns the value of the Unix timestamp that the log message was broadcast.

type Message

type Message struct {
	// Title is a string to use as the title of a "broadcast" message.
	Title string
	// Body is a string to use as the body of a "broadcast" message.
	Body string
	// Images is zero or more `image.Image` instances to be included with a "broadcast" messages.
	// Images are encoded according to rules implemented by service or target -specific implementation
	// of the `Broadcaster` interface.
	Images []image.Image
}

Message defines a struct containing properties to "broadcast". The semantics of these properties are determined by the server or target -specific implementation of the `Broadcaster` interface.

type MultiBroadcaster

type MultiBroadcaster struct {
	Broadcaster
	// contains filtered or unexported fields
}

func (*MultiBroadcaster) BroadcastMessage

func (b *MultiBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)

type NullBroadcaster

type NullBroadcaster struct {
	Broadcaster
}

func (*NullBroadcaster) BroadcastMessage

func (b *NullBroadcaster) BroadcastMessage(ctx context.Context, msg *Message) (uid.UID, error)