irdata

README

irdata

Golang module to simplify access to the iRacing /data API from go

Setup

go get github.com/popmonkey/irdata

api := irdata.Open(context.Background)

Authentication

You can use the provided utility function to request creds from the terminal:

var credsProvider irdata.CredsFromTerminal

api.AuthWithProvideCreds(credsProvider.GetCreds)

You can specify the username, password yourself:

var myCreds struct{}

func (myCreds) GetCreds() {
    return []byte("prost"), []byte("senna")
}

api.AuthWithProvidedCreds(myCreds)

You can also store your credentials in a file encrypted using a keyfile:

var credsProvider irdata.CredsFromTerminal

irdata.SaveProvidedCredsToFile(keyFn, credsFn, credsProvider)

After you have a creds file you can load these into your session like so:

api.AuthWithCredsFromFile(keyFn, credsFn)

Creating and protecting the keyfile

For the key file, you need to create a random string of 16, 24, or 32 bytes and base64 encode it into a file. The file must be set to read only by user (0400) and it is recommended this lives someplace safe.

Example key file creation in Linux or OS X:

openssl rand -base64 32 > ~/my.key && chmod 0400 ~/my.key

[!WARNING] Don't check your keys into git ;)

Accessing the /data API

Once authenticated, you can query the API by URI, for example:

data, err := api.Get("/data/member/info")

If successful, this returns a []byte array containing the JSON response. See the profile example for some json handling logic.

The API is lightly documented via the /data API itself. Check out the latest version and track changes to it.

Using the cache

The iRacing /data API imposes a rate limit which can become problematic especially when running your program over and over such as during development.

irdata therefore provides a caching layer which you can use to avoid making calls to the actual iRacing API.

api.EnableCache(".cache")

data, err := api.GetWithCache("/data/member/info", time.Duration(15)*time.Minute)

Subsequent calls to the same URI (with same parameters) over the next 15 minutes will return data from the local cache before calling the iRacing /data API again.

Chunked responses

Some iRacing data APIs returns data in chunks (e.g. /data/results/search_series). When irdata detects this it will fetch each chunk and then merge the results into a single json string. Note that this object could be huge.

Debugging

You can turn on verbose logging in order to debug your sessions. This will use the logrus module to write to stderr.

api.EnableDebug()

Development

git clone git@github.com:popmonkey/irdata.git

[!NOTE] Keyfiles must have permissions set to 0400. The example and test keys that are checked into this repository need to be adjust after cloning/pulling

chmod 0400 example/example.key testdata/test.key

Run tests:

go test

These tests run without actually reaching out to the API. To run the complete gamut of tests you need to specify an existing key and creds file (such as those created in the examples) by setting environment variables IRDATA_TEST_KEY to point to the keyfile and IRDATA_TEST_CREDS to point to the creds file encrypted by the key:

IRDATA_TEST_KEY=/path/to/key IRDATA_TEST_CREDS=/path/to/creds go test

Run examples:

pushd examples/profile
go run profile.go
popd

Documentation

Overview

Package irdata provides simplified access to the [iRacing /data API]

• Authentication is handled internally and credentials can be saved in an encrypted credentials file protected by a secure key file.
• The iRacing /data API returns data in the form of S3 links. This package delivers the S3 results directly handling all the redirection.
• If an API endpoint returns chunked data, irdata will handle the chunk fetching and return a merged object (note, it could be *huge*)
• An optional caching layer is provided to minimize direct calls to the /data endpoints themselves as those are rate limited.

[iRacing /data API] https://forums.iracing.com/discussion/15068/general-availability-of-data-api/p1

Index

• func SaveProvidedCredsToFile(keyFilename string, authFilename string, authSource CredsProvider) error
• type Chunk
• type CredsFromTerminal
  • func (CredsFromTerminal) GetCreds() ([]byte, []byte, error)
• type CredsProvider
• type Irdata
  • func Open(ctx context.Context) *Irdata
  • func (i *Irdata) AuthWithCredsFromFile(keyFilename string, authFilename string) error
  • func (i *Irdata) AuthWithProvideCreds(authSource CredsProvider) error
  • func (i *Irdata) Close()
  • func (i *Irdata) DisableDebug()
  • func (i *Irdata) EnableCache(cacheDir string) error
  • func (i *Irdata) EnableDebug()
  • func (i *Irdata) Get(uri string) ([]byte, error)
  • func (i *Irdata) GetWithCache(uri string, ttl time.Duration) ([]byte, error)
  • func (i *Irdata) SetLogLevel(logLevel LogLevel)
• type LogLevel

Functions

func SaveProvidedCredsToFile

func SaveProvidedCredsToFile(keyFilename string, authFilename string, authSource CredsProvider) error

SaveProvidedCredsToFile calls the provided function for the username and password and then saves these credentials to authFilename using the key within the keyFilename

This function will panic out on errors

Types

type Chunk

type Chunk struct {
	Number   int
	FileName string
	Data     []byte
}

type CredsFromTerminal

type CredsFromTerminal struct{}

func (CredsFromTerminal) GetCreds

func (CredsFromTerminal) GetCreds() ([]byte, []byte, error)

CredsFromTerminal can be used with any of the SetCreds* functions and will prompt for iRacing credentials (username and password) from the terminal.

type CredsProvider

type CredsProvider interface {
	GetCreds() ([]byte, []byte, error)
}

type Irdata

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

func Open

func Open(ctx context.Context) *Irdata

func (*Irdata) AuthWithCredsFromFile

func (i *Irdata) AuthWithCredsFromFile(keyFilename string, authFilename string) error

AuthWithCredsFromFile loads the username and password from a file at authFilename and encrypted with the key in keyFilename.

func (*Irdata) AuthWithProvideCreds

func (i *Irdata) AuthWithProvideCreds(authSource CredsProvider) error

AuthWithProvideCreds calls the provided function for the username and password

func (*Irdata) Close

func (i *Irdata) Close()

Close Calling Close when done is important when using caching - this will compact the cache.

func (*Irdata) DisableDebug

func (i *Irdata) DisableDebug()

DisableDebug disables debug logging

func (*Irdata) EnableCache

func (i *Irdata) EnableCache(cacheDir string) error

EnableCache enables on the optional caching layer which will use the directory path provided as cacheDir

func (*Irdata) EnableDebug

func (i *Irdata) EnableDebug()

EnableDebug enables debug logging which uses the logrus module

func (*Irdata) Get

func (i *Irdata) Get(uri string) ([]byte, error)

Get returns the result value for the uri provided (e.g. "/data/member/info")

The value returned is a JSON byte array and a potential error.

Get will automatically retry 5 times if iRacing returns 500 errors

func (*Irdata) GetWithCache

func (i *Irdata) GetWithCache(uri string, ttl time.Duration) ([]byte, error)

GetWithCache will first check the local cache for an unexpired result and will the call Get with the uri provided.

The ttl defines for how long the results should be cached.

You must call EnableCache before calling GetWithCache NOTE: If data is fetched this will return the data even if it can't be written to the cache (along with an error)

func (*Irdata) SetLogLevel

func (i *Irdata) SetLogLevel(logLevel LogLevel)

SetLogLevel sets the loging level using the logrus module

type LogLevel

type LogLevel int8

const (
	LogLevelFatal LogLevel = iota
	LogLevelError LogLevel = iota
	LogLevelWarn  LogLevel = iota
	LogLevelInfo  LogLevel = iota
	LogLevelDebug LogLevel = iota
)