registry

package module
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Mar 16, 2020 License: GPL-3.0 Imports: 11 Imported by: 0

README

getwtxt|registry

Build Status   GoDoc

twtxt Registry Library for Go

getwtxt/registry helps you implement twtxt registries in Go. It uses no third-party dependencies whatsoever, only the standard library, and has no global state. Specifying your own http.Client for requests is encouraged, with a sensible default available by passing nil to the constructor.

Using the Library

You can grab a copy by issuing:

$ go get -u github.com/getwtxt/registry

If you're using Go Modules, go get is smart enough to snag the most recent tagged version. Subsequent runs of go get -u will update the local copy.

Then, in the appropriate source file of your project, include this in your import statement:

import (
  "github.com/getwtxt/registry"
)

Documentation

The code is commented, so feel free to browse the files themselves. Alternatively, the generated documentation can be found at:

godoc.org/github.com/getwtxt/registry

Contributions

All contributions are very welcome! Please feel free to submit a PR if you find something that needs improvement.

Notes

Documentation

Overview

Package registry implements functions and types that assist in the creation and management of a twtxt registry.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetTwtxt

func GetTwtxt(urlKey string, client *http.Client) ([]byte, bool, error)

GetTwtxt fetches the raw twtxt file data from the user's provided URL, after validating the URL. If the returned boolean value is false, the fetched URL is a single user's twtxt file. If true, the fetched URL is the output of another registry's /api/plain/tweets. The output of GetTwtxt should be passed to either ParseUserTwtxt or ParseRegistryTwtxt, respectively. Generally, the *http.Client inside a given Registry instance should be passed to GetTwtxt. If the *http.Client passed is nil, Registry will use a preconstructed client with a timeout of 10s and all other values set to default.

func ReduceToPage

func ReduceToPage(page int, data []string) []string

ReduceToPage returns the passed 'page' worth of output. One page is twenty items. For example, if 2 is passed, it will return data[20:40]. According to the twtxt registry specification, queries should accept a "page" value.

func SortByTime

func SortByTime(tm ...TimeMap) ([]string, error)

SortByTime returns a string slice of the query results, sorted by timestamp in descending order (newest first).

Types

type Registrar added in v0.4.0

type Registrar interface {
	Put(user *User) error
	Get(urlKey string) (*User, error)
	DelUser(urlKey string) error
	UpdateUser(urlKey string) error
	GetUserStatuses(urlKey string) (TimeMap, error)
	GetStatuses() (TimeMap, error)
}

Registrar implements the minimum amount of methods for a functioning Registry.

type Registry added in v0.4.0

type Registry struct {
	// Provided to aid in concurrency-safe
	// reads and writes to a given registry
	// Users map.
	Mu sync.RWMutex

	// The registry's user data is contained
	// in this map. The functions within this
	// library expect the key to be the URL of
	// a given user's twtxt file.
	Users map[string]*User

	// The client to use for HTTP requests.
	// If nil is passed to NewIndex(), a
	// client with a 10 second timeout
	// and all other values as default is
	// used.
	HTTPClient *http.Client
}

Registry enables the bulk of a registry's user data storage and access.

func New added in v0.4.0

func New(client *http.Client) *Registry

New returns an initialized Registry instance.

func (*Registry) AddUser added in v0.4.0

func (registry *Registry) AddUser(nickname, urlKey string, ipAddress net.IP, statuses TimeMap) error

AddUser inserts a new user into the Registry.

func (*Registry) CrawlRemoteRegistry added in v0.4.0

func (registry *Registry) CrawlRemoteRegistry(urlKey string) error

CrawlRemoteRegistry scrapes all nicknames and user URLs from a provided registry. The urlKey passed to this function must be in the form of https://registry.example.com/api/plain/users

func (*Registry) DelUser added in v0.4.0

func (registry *Registry) DelUser(urlKey string) error

DelUser removes a user and all associated data from the Registry.

func (*Registry) DiffTwtxt added in v0.4.0

func (registry *Registry) DiffTwtxt(urlKey string) (bool, error)

DiffTwtxt issues a HEAD request on the user's remote twtxt data. It then checks the Content-Length header. If it's different from the stored result of the previous Content-Length header, update the stored value for a given user and return true. Otherwise, return false. In some error conditions, such as the user not being in the registry, it returns true. In other error conditions considered "unrecoverable," such as the supplied URL being invalid, it returns false.

func (*Registry) Get added in v0.4.0

func (registry *Registry) Get(urlKey string) (*User, error)

Get returns the User associated with the provided URL key in the Registry.

func (*Registry) GetStatuses added in v0.4.0

func (registry *Registry) GetStatuses() (TimeMap, error)

GetStatuses returns a TimeMap containing all statuses from all users in the Registry.

func (*Registry) GetUserStatuses added in v0.4.0

func (registry *Registry) GetUserStatuses(urlKey string) (TimeMap, error)

GetUserStatuses returns a TimeMap containing single user's statuses

func (*Registry) Put added in v0.4.0

func (registry *Registry) Put(user *User) error

Put inserts a given User into an Registry. The User being pushed need only have the URL field filled. All other fields may be empty. This can be destructive: an existing User in the Registry will be overwritten if its User.URL is the same as the User.URL being pushed.

func (*Registry) QueryAllStatuses added in v0.4.0

func (registry *Registry) QueryAllStatuses() ([]string, error)

QueryAllStatuses returns all statuses in the Registry as a slice of strings sorted by timestamp.

func (*Registry) QueryInStatus added in v0.4.0

func (registry *Registry) QueryInStatus(substring string) ([]string, error)

QueryInStatus returns all statuses in the Registry that contain the provided substring (tag, mention URL, etc).

func (*Registry) QueryUser added in v0.4.0

func (registry *Registry) QueryUser(term string) ([]string, error)

QueryUser checks the Registry for usernames or user URLs that contain the term provided as an argument. Entries are returned sorted by the date they were added to the Registry. If the argument provided is blank, return all users.

func (*Registry) UpdateUser added in v0.4.0

func (registry *Registry) UpdateUser(urlKey string) error

UpdateUser scrapes an existing user's remote twtxt.txt file. Any new statuses are added to the user's entry in the Registry. If the remote twtxt data's reported Content-Length does not differ from what is stored, an error is returned.

type TimeMap

type TimeMap map[time.Time]string

TimeMap holds extracted and processed user data as a string. A time.Time value is used as the key.

func NewTimeMap

func NewTimeMap() TimeMap

NewTimeMap returns an initialized TimeMap.

func ParseUserTwtxt

func ParseUserTwtxt(twtxt []byte, nickname, urlKey string) (TimeMap, error)

ParseUserTwtxt takes a fetched twtxt file in the form of a slice of bytes, parses it, and returns it as a TimeMap. The output may then be passed to Index.AddUser()

type TimeSlice

type TimeSlice []time.Time

TimeSlice is a slice of time.Time used for sorting a TimeMap by timestamp.

func (TimeSlice) Len

func (t TimeSlice) Len() int

Len returns the length of the TimeSlice to be sorted. This helps satisfy sort.Interface.

func (TimeSlice) Less

func (t TimeSlice) Less(i, j int) bool

Less returns true if the timestamp at index i is after the timestamp at index j in a given TimeSlice. This results in a descending (reversed) sort order for timestamps rather than ascending. This helps satisfy sort.Interface.

func (TimeSlice) Swap

func (t TimeSlice) Swap(i, j int)

Swap transposes the timestamps at the two given indices for the TimeSlice receiver. This helps satisfy sort.Interface.

type User

type User struct {
	// Provided to aid in concurrency-safe
	// reads and writes. In most cases, the
	// mutex in the associated Index should be
	// used instead. This mutex is provided
	// should the library user need to access
	// a User independently of an Index.
	Mu sync.RWMutex

	// Nick is the user-specified nickname.
	Nick string

	// The URL of the user's twtxt file
	URL string

	// The reported last modification date
	// of the user's twtxt.txt file.
	LastModified string

	// The IP address of the user is optionally
	// recorded when submitted via POST.
	IP net.IP

	// The timestamp, in RFC3339 format,
	// reflecting when the user was added.
	Date string

	// A TimeMap of the user's statuses
	// from their twtxt file.
	Status TimeMap
}

User holds a given user's information and statuses.

func NewUser

func NewUser() *User

NewUser returns a pointer to an initialized User

func ParseRegistryTwtxt

func ParseRegistryTwtxt(twtxt []byte) ([]*User, error)

ParseRegistryTwtxt takes output from a remote registry and outputs the accessible user data via a slice of Users.

func (*User) FindInStatus

func (userdata *User) FindInStatus(substring string) TimeMap

FindInStatus takes a user's statuses and looks for a given substring. Returns the statuses that include the substring as a TimeMap.

Jump to

Keyboard shortcuts

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