caprice

README

About

A Go client for RANDOM.org. Generate truly random numbers in your code!

Example

package main

import (
	"github.com/AkshatM/caprice"
	"fmt"
)

func main() {
	rng := caprice.TrueRNG(<api key>)

	// generate 10 integers in base 10 between 1 and 100 with no duplicates 
	intArray, err := rng.GenerateIntegers(10, 1, 100, false)
	fmt.Printf("%v, intArray)

	// same as last time, but get back the entirety of the JSON response as a Result struct
	result, err := rng.GenerateIntegersRaw(10, 1, 100, false)
	fmt.Printf("%+v", result)

	// same as last time, but get back a structure that contains all the information you need
	// to verify the data you received along with the data itself in convenient format.
	verifiableResult, err := rng.GenerateSignedIntegers(10, 1, 100, false)
	fmt.Printf("%v", verifiableResult.Data) // actual data
	fmt.Printf("%+v", verifiableResult)
}

Installation

For now,

go get -u github.com/AkshatM/caprice

Documentation

Working on getting this into Godoc. For now, consult the source.

With the exception of verifySignature, all API calls are supported as listed here and here.

• Per Go convention, all API calls begin with capitalised letters.
• Every basic API call x has a corresponding method called xRaw that will return a Response object. e.g. GenerateIntegers has GenerateIntegersRaw. This is useful if you need access to any of the other response items RANDOM.org returns. Signed methods already return the raw JSONified data as well as the actual data supplied, so no equivalent exists for signed methods.
• verifySignature currently has issues :( however, you can still verify the integrity of your data by taking the signature and raw fields of the result struct from a signed method manually.

Road Map

1.0:

• Add support for using advisoryDelay, making this code truly thread-safe.
• Get documentation up.
• Add mocked network calls for decoupled testing.

Documentation

Index

• func Request(method string, params interface{}) (Response, Error)
• func SignedRequest(method string, params interface{}) (Response, Error)
• func TrueRNG(apiKey string) trueRNG
• type BlobsReq
• type DecimalFractionsReq
• type Error
  • func (e Error) Error() string
• type GaussiansReq
• type IntegersReq
• type Random
• type RequestShell
• type Response
• type ResponseShell
• type Result
  • func (r Result) Content() interface{}
• type SignedFloatData
• type SignedIntegerData
• type SignedResult
  • func (sr SignedResult) Content() interface{}
• type SignedStringData
• type Status
  • func (s Status) Content() interface{}
• type StatusReq
• type StringsReq
• type UUIDsReq
• type VerifiedSignature
  • func (vs VerifiedSignature) Content() interface{}
• type VerifySignatureReq

Functions

func Request

func Request(method string, params interface{}) (Response, Error)

func SignedRequest

func SignedRequest(method string, params interface{}) (Response, Error)

func TrueRNG

func TrueRNG(apiKey string) trueRNG

A helper function that will return a new trueRNG object

Types

type BlobsReq

type BlobsReq struct {
	ApiKey string `json:"apiKey"`
	N      int    `json:"n"`
	Size   int    `json:"size"`
	Format string `json:"format"`
}

type DecimalFractionsReq

type DecimalFractionsReq struct {
	ApiKey        string `json:"apiKey"`
	N             int    `json:"n"`
	DecimalPlaces int    `json:"decimalPlaces"`
	Replacement   bool   `json:"replacement"`
}

type Error

type Error struct {
	Code    int           `json:"code"`
	Message string        `json:"message"`
	Data    []interface{} `json:"data,omitempty"`
}

Core error object. Includes error message, the status code returned by the API, and optional data returned by the upstream API.

func (Error) Error

func (e Error) Error() string

type GaussiansReq

type GaussiansReq struct {
	ApiKey            string  `json:"apiKey"`
	N                 int     `json:"n"`
	Mean              float64 `json:"mean"`
	StandardDeviation float64 `json:"standardDeviation"`
	SignificantDigits int     `json:"significantDigits"`
}

type IntegersReq

type IntegersReq struct {
	ApiKey      string `json:"apiKey"`
	N           int    `json:"n"`
	Min         int    `json:"min"`
	Max         int    `json:"max"`
	Replacement bool   `json:"replacement"`
}

type Random

type Random struct {
	Data           []interface{} `json:"data"`
	CompletionTime string        `json:"completionTime"`
	SerialNumber   int           `json:"serialNumber"`
	HashedApiKey   string        `json:"hashedApiKey"`
}

A deeply nested inner JSON object contained inside ResponseShell.Random, which includes everything we asked for. For basic methods, `Data` and `CompletionTime` are returned. For signed methods, the values `HashedApiKey` and `SerialNumber` are also returned.

type RequestShell

type RequestShell struct {
	Version string      `json:"jsonrpc"`
	Params  interface{} `json:"params"`
	Method  string      `json:"method"`
	Id      int         `json:"id"`
}

The outer JSON wrapper we send in our request body. It contains `params`, which is a JSON object containing all the method parameters. Typically, a struct implementing RequestShell will be populated for you.

type Response

type Response interface {
	Content() interface{}
}

An interface that all Status, Result and SignedResult implement so that they can be returned as valid outputs of the Request and SignedRequest functions. The expectation is that any struct that satisfies this interface has the actual data we would care about.

type ResponseShell

type ResponseShell struct {
	Version string          `json:"jsonrpc"`
	Result  json.RawMessage `json:"result"`
	Error   Error           `json:"error"`
	Id      int             `json:"id"`
}

The outer JSON wrapper we receive in our request body. It contains `result`, which is a JSON object containing an object containing all the actual data we care for. `error` is returned from the API in lieu of `result` in the event of an error. 'id' and versions are constants supplied and returned by the API.

type Result

type Result struct {
	Random        Random `json:"random"`
	BitsUsed      int    `json:"bitsUsed"`
	BitsLeft      int    `json:"bitsLeft"`
	RequestsLeft  int    `json:"requestsLeft"`
	AdvisoryDelay int    `json:"advisoryDelay"`
}

A nested inner JSON wrapper around Random within ResponseShell.Result. It includes some basic diagnostic information as well. One of four types implementing Response interface

func (Result) Content

func (r Result) Content() interface{}

type SignedFloatData

type SignedFloatData struct {
	Raw          json.RawMessage
	HashedApiKey string
	SerialNumber int
	Data         []float64
	Signature    string
}

type SignedIntegerData

type SignedIntegerData struct {
	Raw          json.RawMessage
	HashedApiKey string
	SerialNumber int
	Data         []int
	Signature    string
}

type SignedResult

type SignedResult struct {
	Raw           json.RawMessage `json:"random"`
	Signature     string          `json:"signature"`
	BitsUsed      int             `json:"bitsUsed"`
	BitsLeft      int             `json:"bitsLeft"`
	RequestsLeft  int             `json:"requestsLeft"`
	AdvisoryDelay int             `json:"advisoryDelay"`
}

A nested inner JSON wrapper around Random within ResponseShell.Result. It includes some basic diagnostic information as well as a signature to verify the source of the data. One of four types implementing Response interface. Raw is an alias for Random here.

func (SignedResult) Content

func (sr SignedResult) Content() interface{}

type SignedStringData

type SignedStringData struct {
	Raw          json.RawMessage
	HashedApiKey string
	Data         []string
	SerialNumber int
	Signature    string
}

type Status

type Status struct {
	Status        string `json:"status"`
	CreationTime  string `json:"creationTime"`
	BitsLeft      int    `json:"bitsLeft"`
	RequestsLeft  int    `json:"requestsLeft"`
	TotalBits     int    `json:"totalBits"`
	TotalRequests int    `json:"totalRequests"`
}

A nested inner JSON object within ResponseShell.Result. It includes only basic diagnostic information. One of four types implementing Response interface; returned directly as part of the GetUsage method.

func (Status) Content

func (s Status) Content() interface{}

type StatusReq

type StatusReq struct {
	ApiKey string `json:"apiKey"`
}

type StringsReq

type StringsReq struct {
	ApiKey      string `json:"apiKey"`
	N           int    `json:"n"`
	Length      int    `json:"length"`
	Characters  string `json:"characters"`
	Replacement bool   `json:"replacement"`
}

type UUIDsReq

type UUIDsReq struct {
	ApiKey string `json:"apiKey"`
	N      int    `json:"n"`
}

type VerifiedSignature

type VerifiedSignature struct {
	Authenticity bool `json:"authenticiity"`
}

A nested inner JSON object within ResponseShell.Result. It includes only basic diagnostic information. One of four types implementing Response interface; returned directly as part of the GetUsage method.

func (VerifiedSignature) Content

func (vs VerifiedSignature) Content() interface{}

type VerifySignatureReq

type VerifySignatureReq struct {
	Raw       map[string]interface{} `json:"random"`
	Signature string                 `json:"signature"`
}