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 hex 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:

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 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 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 return everything as one JSON blob containing an array of chunks (marshaled as irdata.Chunk). E.g.

[
    {
        "Number": 0,
        "FileName": "1b57c5c8a0bd9ff081a8b2a20187219ee5259b75451eef1e5e8d7b7e7a4ade42.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240618T192913Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Credential=AKIAUO6OO4A3357USLO7%2F20240618%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=dc1c2567163436564045e912dc0fb5043f5720f1b30e3de77a02923f10b3ca70",
        "Data": "[<json from the chunk>]"
    },
    {
        "Number": 1,
        ...
    }
]

You can unmarshal this to an array of irdata.Chunk like so:

var chunks []irdata.Chunk

json.Unmarshal(data, &chunks)

Debugging

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

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

Run example:

pushd example
go run example.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.
• 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)
• type Chunk
• type CredsFromTerminal
  • func (CredsFromTerminal) GetCreds() ([]byte, []byte)
• 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) 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)

Functions

func SaveProvidedCredsToFile

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

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)

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)
}

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) 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 log 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