Package captcha ===================== import "github.com/dchest/captcha" Package captcha implements generation and verification of image and audio CAPTCHAs. Examples -------- ![Image](https://github.com/dchest/captcha/raw/master/capgen/example.png) [Audio](https://github.com/dchest/captcha/raw/master/capgen/example.wav) Constants --------- ``` go const ( // Standard number of digits in captcha. StdLength = 6 // The number of captchas created that triggers garbage collection used // by default store. CollectNum = 100 // Expiration time of captchas used by default store. Expiration = 10 * 60 // 10 minutes ) ``` ``` go const ( // Standard width and height of a captcha image. StdWidth = 300 StdHeight = 80 ) ``` Variables --------- ``` go var ErrNotFound = os.NewError("captcha with the given id not found") ``` Functions --------- ### func Collect func Collect() Collect deletes expired or used captchas from the internal storage. It is called automatically by New function every CollectNum generated captchas, but still exported to enable freeing memory manually if needed. Collection is launched in a new goroutine. ### func New func New(length int) (id string) New creates a new captcha of the given length, saves it in the internal storage, and returns its id. ### func RandomDigits func RandomDigits(length int) []byte RandomDigits returns a byte slice of the given length containing random digits in range 0-9. ### func Reload func Reload(id string) bool Reload generates and remembers new digits for the given captcha id. This function returns false if there is no captcha with the given id. After calling this function, the image or audio presented to a user must be refreshed to show the new captcha representation (WriteImage and WriteAudio will write the new one). ### func Server func Server(w, h int) http.Handler Server returns a handler that serves HTTP requests with image or audio representations of captchas. Image dimensions are accepted as arguments. The server decides which captcha to serve based on the last URL path component: file name part must contain a captcha id, file extension — its format (PNG or WAV). For example, for file name "B9QTvDV1RXbVJ3Ac.png" it serves an image captcha with id "B9QTvDV1RXbVJ3Ac", and for "B9QTvDV1RXbVJ3Ac.wav" it serves the same captcha in audio format. To serve an audio captcha as downloadable file, append "?get" to URL. To reload captcha (get a different solution for the same captcha id), append "?reload=x" to URL, where x may be anything (for example, current time or a random number to make browsers refetch an image instead of loading it from cache). ### func SetCustomStore func SetCustomStore(s Store) SetCustomStore sets custom storage for captchas, replacing the default memory store. This function must be called before generating any captchas. ### func Verify func Verify(id string, digits []byte) bool Verify returns true if the given digits are the ones that were used to create the given captcha id. The function deletes the captcha with the given id from the internal storage, so that the same captcha can't be verified anymore. ### func VerifyString func VerifyString(id string, digits string) bool VerifyString is like Verify, but accepts a string of digits. It removes spaces and commas from the string, but any other characters, apart from digits and listed above, will cause the function to return false. ### func WriteAudio func WriteAudio(w io.Writer, id string) os.Error WriteAudio writes WAV-encoded audio representation of the captcha with the given id. ### func WriteImage func WriteImage(w io.Writer, id string, width, height int) os.Error WriteImage writes PNG-encoded image representation of the captcha with the given id. The image will have the given width and height. Types ----- ``` go type Audio struct { // contains unexported fields } ``` ### func NewAudio func NewAudio(digits []byte) *Audio NewImage returns a new audio captcha with the given digits, where each digit must be in range 0-9. ### func (*Audio) EncodedLen func (a *Audio) EncodedLen() int EncodedLen returns the length of WAV-encoded audio captcha. ### func (*Audio) WriteTo func (a *Audio) WriteTo(w io.Writer) (n int64, err os.Error) WriteTo writes captcha audio in WAVE format into the given io.Writer, and returns the number of bytes written and an error if any. ``` go type Image struct { *image.NRGBA // contains unexported fields } ``` ### func NewImage func NewImage(digits []byte, width, height int) *Image NewImage returns a new captcha image of the given width and height with the given digits, where each digit must be in range 0-9. ### func (*Image) WriteTo func (img *Image) WriteTo(w io.Writer) (int64, os.Error) WriteTo writes captcha image in PNG format into the given writer. ``` go type Store interface { // Set sets the digits for the captcha id. Set(id string, digits []byte) // Get returns stored digits for the captcha id. Clear indicates // whether the captcha must be deleted from the store. Get(id string, clear bool) (digits []byte) // Collect deletes expired captchas from the store. For custom stores // this method is not called automatically, it is only wired to the // package's Collect function. Custom stores must implement their own // procedure for calling Collect, for example, in Set method. Collect() } ``` An object implementing Store interface can be registered with SetCustomStore function to handle storage and retrieval of captcha ids and solutions for them, replacing the default memory store. ### func NewMemoryStore func NewMemoryStore(collectNum int, expiration int64) Store NewMemoryStore returns a new standard memory store for captchas with the given collection threshold and expiration time in seconds. The returned store must be registered with SetCustomStore to replace the default one. Bugs ---- [Not our bug] Google Chrome 10 plays unsigned 8-bit PCM WAVE audio on Mac with horrible distortions. Issue: http://code.google.com/p/chromium/issues/detail?id=70730. This has been fixed, and version 12 will play them properly. While Image conforms to io.WriterTo interface, its WriteTo method returns 0 instead of the actual bytes written because png.Encode doesn't report this. Subdirectories -------------- capgen example generate