red

README

go-red

go-red is a go module for the Redacted API.

Documentation

Overview

Package red provides an API client for red.

The module does not try to clean up the API. It returns the Structs as they are received in JSON. Some return values for different methods can be similar but are not exactly the same in most cases.

Requests are rate limited by default to reduce the risk of sending too many requests.

Index

• Constants
• Variables
• type ArtistParams
• type ArtistResponse
• type Client
  • func NewClient(opts ...Option) *Client
  • func (c *Client) Artist(params ArtistParams) (*ArtistResponse, error)
  • func (c *Client) Download(params DownloadParams) (map[string]string, io.ReadCloser, error)
  • func (c *Client) Group(params GroupParams) (*GroupResponse, error)
  • func (c *Client) Search(params SearchParams) (*SearchResponse, error)
  • func (c *Client) Torrent(params TorrentParams) (*TorrentResponse, error)
• type Collage
• type DownloadParams
• type FileList
  • func (f FileList) Decode() (map[string]uint32, error)
• type Group
• type GroupArtist
• type GroupParams
• type GroupResponse
• type MusicInfo
• type Option
  • func WithAPIKey(key string) Option
  • func WithBaseURL(u *url.URL) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithRateLimiter(r *rate.Limiter) Option
  • func WithUserAgent(userAgent string) Option
• type Response
• type SearchArtist
• type SearchParams
• type SearchResponse
• type SearchResult
• type SearchTorrent
• type Torrent
• type TorrentParams
• type TorrentResponse

Constants

const (
	// LimiterDefaultRate defines the default rate for the request rate limiter.
	LimiterDefaultRate = 10 * time.Second

	// LimiterDefaultTokens defines the amount of requests within a default rate duration.
	LimiterDefaultTokens = 5

	DefaultBaseURL   = "https://redacted.ch"
	DefaultUserAgent = "go-red/0.1"
	Path             = "/ajax.php"
	ActionKey        = "action"

	StatusSuccess = "success"
)

Variables

var ErrFailure = errors.New("response returned status failure")

ErrFailure respresents a status "failure" error.

var ErrParamsRequired = errors.New("params required")

ErrParamsRequired respresents a required parameter error.

var ErrStatus = errors.New("status code error")

ErrStatus respresents a non success status code error.

Types

type ArtistParams

type ArtistParams struct {
	ID       uint   `url:"id,omitempty"`
	Name     string `url:"artistname,omitempty"`
	Releases bool   `url:"artistreleases,omitempty"`
}

type ArtistResponse

type ArtistResponse struct {
	ID                   uint   `json:"id"`
	Name                 string `json:"name"`
	NotificationsEnabled bool   `json:"notificationsEnabled"`
	HasBookmarked        bool   `json:"hasBookmarked"`
	Image                string `json:"image"`
	Body                 string `json:"body"`
	VanityHouse          bool   `json:"vanityHouse"`
	Tags                 []struct {
		Name  string `json:"name"`
		Count uint   `json:"count"`
	} `json:"tags"`
	SimilarArtists []interface{} `json:"similarArtists"`
	Statistics     struct {
		NumGroups   uint `json:"numGroups"`
		NumTorrents uint `json:"numTorrents"`
		NumSeeders  uint `json:"numSeeders"`
		NumLeechers uint `json:"numLeechers"`
		NumSnatches uint `json:"numSnatches"`
	} `json:"statistics"`
	Torrentgroup []struct {
		GroupID              uint     `json:"groupId"`
		GroupName            string   `json:"groupName"`
		GroupYear            uint     `json:"groupYear"`
		GroupRecordLabel     string   `json:"groupRecordLabel"`
		GroupCatalogueNumber string   `json:"groupCatalogueNumber"`
		Tags                 []string `json:"tags"`
		ReleaseType          int      `json:"releaseType"`
		GroupVanityHouse     bool     `json:"groupVanityHouse"`
		HasBookmarked        bool     `json:"hasBookmarked"`
		Torrent              []struct {
			ID                  uint   `json:"id"`
			GroupID             uint   `json:"groupId"`
			Media               string `json:"media"`
			Format              string `json:"format"`
			Encoding            string `json:"encoding"`
			RemasterYear        uint   `json:"remasterYear"`
			Remastered          bool   `json:"remastered"`
			RemasterTitle       string `json:"remasterTitle"`
			RemasterRecordLabel string `json:"remasterRecordLabel"`
			Scene               bool   `json:"scene"`
			HasLog              bool   `json:"hasLog"`
			HasCue              bool   `json:"hasCue"`
			LogScore            uint   `json:"logScore"`
			FileCount           uint   `json:"fileCount"`
			FreeTorrent         bool   `json:"freeTorrent"`
			Size                uint   `json:"size"`
			Leechers            uint   `json:"leechers"`
			Seeders             uint   `json:"seeders"`
			Snatched            uint   `json:"snatched"`
			Time                string `json:"time"`
			HasFile             int    `json:"hasFile"`
		} `json:"torrent"`
	} `json:"torrentgroup"`
	Requests []struct {
		RequestID  int    `json:"requestId"`
		CategoryID int    `json:"categoryId"`
		Title      string `json:"title"`
		Year       int    `json:"year"`
		TimeAdded  string `json:"timeAdded"`
		Votes      int    `json:"votes"`
		Bounty     int    `json:"bounty"`
	} `json:"requests"`
}

type Client

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

func NewClient

func NewClient(opts ...Option) *Client

NewClient creates a new API client for red. It will automatically create a http client and a rate limiter.

To define options the With methods can be used:

    red.NewClient(
	  red.WithAPIKey("abcd"),
	  red.WithBaseURL(u),
    )

To disable the rate limiter, you can use:

WithRateLimiter(nil)

func (*Client) Artist

func (c *Client) Artist(params ArtistParams) (*ArtistResponse, error)

func (*Client) Download

func (c *Client) Download(params DownloadParams) (map[string]string, io.ReadCloser, error)

Download is used to get a Torrent file.

It will return the file parameters including the file name. The torrent as an `io.ReadCloser` and an eventual error.

func (*Client) Group

func (c *Client) Group(params GroupParams) (*GroupResponse, error)

func (*Client) Search

func (c *Client) Search(params SearchParams) (*SearchResponse, error)

func (*Client) Torrent

func (c *Client) Torrent(params TorrentParams) (*TorrentResponse, error)

Torrent returns a torrent based on its params.

type Collage

type Collage struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	NumTorrents int    `json:"numTorrents"`
}

type DownloadParams

type DownloadParams struct {
	ID       int  `url:"id,omitempty"`
	UseToken bool `url:"usetoken,int,omitempty"`
}

type FileList

type FileList string

func (FileList) Decode

func (f FileList) Decode() (map[string]uint32, error)

Decode parses a FileList and returns a map with the file name as key and the size as value.

type Group

type Group struct {
	WikiBody         string    `json:"wikiBody"`
	WikiImage        string    `json:"wikiImage"`
	ID               int       `json:"id"`
	Name             string    `json:"name"`
	Year             int       `json:"year"`
	RecordLabel      string    `json:"recordLabel"`
	CatalogueNumber  string    `json:"catalogueNumber"`
	ReleaseType      int       `json:"releaseType"`
	CategoryID       int       `json:"categoryId"`
	CategoryName     string    `json:"categoryName"`
	Time             string    `json:"time"`
	Collages         []Collage `json:"collages"`
	PersonalCollages []Collage `json:"personalCollages"`
	VanityHouse      bool      `json:"vanityHouse"`
	MusicInfo        MusicInfo `json:"musicInfo"`
}

type GroupArtist

type GroupArtist struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type GroupParams

type GroupParams struct {
	ID   uint   `url:"id,omitempty"`
	Hash string `url:"hash,omitempty"`
}

type GroupResponse

type GroupResponse struct {
	Group    Group     `json:"group"`
	Torrents []Torrent `json:"torrents"`
}

type MusicInfo

type MusicInfo struct {
	Composers []GroupArtist `json:"composers"`
	Dj        []GroupArtist `json:"dj"`
	Artists   []GroupArtist `json:"artists"`
	With      []GroupArtist `json:"with"`
	Conductor []GroupArtist `json:"conductor"`
	RemixedBy []GroupArtist `json:"remixedBy"`
	Producer  []GroupArtist `json:"producer"`
}

type Option

type Option func(*Client)

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey defines the API key to be used.

func WithBaseURL

func WithBaseURL(u *url.URL) Option

WithBaseURL defines the API's base url.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient allows to replace the http client.

func WithRateLimiter

func WithRateLimiter(r *rate.Limiter) Option

WithHTTPClient allows to replace the rate limiter. Set to nil to disable rate limiting.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent allows to change the user agent.

type Response

type Response struct {
	Status   string      `json:"status"`
	Response interface{} `json:"response"`
}

Response defines a generic API response.

type SearchArtist

type SearchArtist struct {
	ID      int    `json:"id"`
	Name    string `json:"name"`
	Aliasid int    `json:"aliasid"`
}

type SearchParams

type SearchParams struct {
	SearchString string `url:"searchstr,omitempty"`
	Page         uint8  `url:"page,omitempty"`
	ArtistName   string `url:"artistname,omitempty"`
	GroupName    string `url:"groupname,omitempty"`
}

type SearchResponse

type SearchResponse struct {
	CurrentPage int            `json:"currentPage"`
	Pages       int            `json:"pages"`
	Results     []SearchResult `json:"results"`
}

type SearchResult

type SearchResult struct {
	GroupID       int             `json:"groupId"`
	GroupName     string          `json:"groupName"`
	Artist        string          `json:"artist"`
	Tags          []string        `json:"tags"`
	Bookmarked    bool            `json:"bookmarked"`
	VanityHouse   bool            `json:"vanityHouse"`
	GroupYear     int             `json:"groupYear"`
	ReleaseType   string          `json:"releaseType"`
	GroupTime     int64           `json:"groupTime,string"`
	MaxSize       int             `json:"maxSize"`
	TotalSnatched int             `json:"totalSnatched"`
	TotalSeeders  int             `json:"totalSeeders"`
	TotalLeechers int             `json:"totalLeechers"`
	Torrents      []SearchTorrent `json:"torrents"`
}

type SearchTorrent

type SearchTorrent struct {
	TorrentID               int            `json:"torrentId"`
	EditionID               int            `json:"editionId"`
	Artists                 []SearchArtist `json:"artists"`
	Remastered              bool           `json:"remastered"`
	RemasterYear            int            `json:"remasterYear"`
	RemasterCatalogueNumber string         `json:"remasterCatalogueNumber"`
	RemasterTitle           string         `json:"remasterTitle"`
	Media                   string         `json:"media"`
	Encoding                string         `json:"encoding"`
	Format                  string         `json:"format"`
	HasLog                  bool           `json:"hasLog"`
	LogScore                int            `json:"logScore"`
	HasCue                  bool           `json:"hasCue"`
	Scene                   bool           `json:"scene"`
	VanityHouse             bool           `json:"vanityHouse"`
	FileCount               int            `json:"fileCount"`
	Time                    string         `json:"time"`
	Size                    int            `json:"size"`
	Snatches                int            `json:"snatches"`
	Seeders                 int            `json:"seeders"`
	Leechers                int            `json:"leechers"`
	IsFreeleech             bool           `json:"isFreeleech"`
	IsNeutralLeech          bool           `json:"isNeutralLeech"`
	IsPersonalFreeleech     bool           `json:"isPersonalFreeleech"`
	CanUseToken             bool           `json:"canUseToken"`
}

type Torrent

type Torrent struct {
	ID                      int      `json:"id"`
	Media                   string   `json:"media"`
	Format                  string   `json:"format"`
	Encoding                string   `json:"encoding"`
	Remastered              bool     `json:"remastered"`
	RemasterYear            int      `json:"remasterYear"`
	RemasterTitle           string   `json:"remasterTitle"`
	RemasterRecordLabel     string   `json:"remasterRecordLabel"`
	RemasterCatalogueNumber string   `json:"remasterCatalogueNumber"`
	Scene                   bool     `json:"scene"`
	HasLog                  bool     `json:"hasLog"`
	HasCue                  bool     `json:"hasCue"`
	LogScore                int      `json:"logScore"`
	FileCount               int      `json:"fileCount"`
	Size                    int      `json:"size"`
	Seeders                 int      `json:"seeders"`
	Leechers                int      `json:"leechers"`
	Snatched                int      `json:"snatched"`
	FreeTorrent             bool     `json:"freeTorrent"`
	Time                    string   `json:"time"`
	Description             string   `json:"description"`
	FileList                FileList `json:"fileList"`
	FilePath                string   `json:"filePath"`
	UserID                  int      `json:"userId"`
	Username                string   `json:"username"`
}

type TorrentParams

type TorrentParams struct {
	ID   uint   `url:"id,omitempty"`
	Hash string `url:"hash,omitempty"`
}

type TorrentResponse

type TorrentResponse struct {
	Group   Group   `json:"group"`
	Torrent Torrent `json:"torrent"`
}