1Package captcha
  2=====================
  3
  4	import "github.com/dchest/captcha"
  5
  6Package captcha implements generation and verification of image and audio
  7CAPTCHAs.
  8
  9A captcha solution is the sequence of digits 0-9 with the defined length.
 10There are two captcha representations: image and audio.
 11
 12An image representation is a PNG-encoded image with the solution printed on
 13it in such a way that makes it hard for computers to solve it using OCR.
 14
 15An audio representation is a WAVE-encoded (8 kHz unsigned 8-bit) sound
 16with the spoken solution (currently in English). To make it hard for
 17computers to solve audio captcha, the voice that pronounces numbers has
 18random speed and pitch, and there is a randomly generated background noise
 19mixed into the sound.
 20
 21This package doesn't require external files or libraries to generate captcha
 22representations; it is self-contained.
 23
 24To make captchas one-time, the package includes a memory storage that stores
 25captcha ids, their solutions, and expiration time. Used captchas are removed
 26from the store immediately after calling Verify or VerifyString, while
 27unused captchas (user loaded a page with captcha, but didn't submit the
 28form) are collected automatically after the predefined expiration time.
 29Developers can also provide custom store (for example, which saves captcha
 30ids and solutions in database) by implementing Store interface and
 31registering the object with SetCustomStore.
 32
 33Captchas are created by calling New, which returns the captcha id.  Their
 34representations, though, are created on-the-fly by calling WriteImage or
 35WriteAudio functions. Created representations are not stored anywhere, so
 36subsequent calls to these functions with the same id will write the same
 37captcha solution, but with a different random representation. Reload
 38function will create a new different solution for the provided captcha,
 39allowing users to "reload" captcha if they can't solve the displayed one
 40without reloading the whole page.  Verify and VerifyString are used to
 41verify that the given solution is the right one for the given captcha id.
 42
 43Server provides an http.Handler which can serve image and audio
 44representations of captchas automatically from the URL. It can also be used
 45to reload captchas.  Refer to Server function documentation for details, or
 46take a look at the example in "example" subdirectory.
 47
 48
 49Examples
 50--------
 51
 52![Image](https://github.com/dchest/captcha/raw/master/capgen/example.png)
 53
 54[Audio](https://github.com/dchest/captcha/raw/master/capgen/example.wav)
 55
 56
 57Constants
 58---------
 59
 60``` go
 61const (
 62    // Default number of digits in captcha solution.
 63    DefaultLen = 6
 64    // The number of captchas created that triggers garbage collection used
 65    // by default store.
 66    CollectNum = 100
 67    // Expiration time of captchas used by default store.
 68    Expiration = 10 * 60 // 10 minutes
 69
 70)
 71```
 72
 73``` go
 74const (
 75    // Standard width and height of a captcha image.
 76    StdWidth  = 240
 77    StdHeight = 80
 78)
 79```
 80
 81
 82Variables
 83---------
 84
 85``` go
 86var ErrNotFound = os.NewError("captcha with the given id not found")
 87```
 88
 89
 90
 91Functions
 92---------
 93
 94### func New
 95
 96	func New() string
 97	
 98New creates a new captcha with the standard length, saves it in the internal
 99storage and returns its id.
100
101### func NewLen
102
103	func NewLen(length int) (id string)
104	
105NewLen is just like New, but accepts length of a captcha solution as the
106argument.
107
108### func RandomDigits
109
110	func RandomDigits(length int) []byte
111	
112RandomDigits returns a byte slice of the given length containing random
113digits in range 0-9.
114
115### func Reload
116
117	func Reload(id string) bool
118	
119Reload generates and remembers new digits for the given captcha id.  This
120function returns false if there is no captcha with the given id.
121
122After calling this function, the image or audio presented to a user must be
123refreshed to show the new captcha representation (WriteImage and WriteAudio
124will write the new one).
125
126### func Server
127
128	func Server(imgWidth, imgHeight int) http.Handler
129	
130Server returns a handler that serves HTTP requests with image or
131audio representations of captchas. Image dimensions are accepted as
132arguments. The server decides which captcha to serve based on the last URL
133path component: file name part must contain a captcha id, file extension —
134its format (PNG or WAV).
135
136For example, for file name "B9QTvDV1RXbVJ3Ac.png" it serves an image captcha
137with id "B9QTvDV1RXbVJ3Ac", and for "B9QTvDV1RXbVJ3Ac.wav" it serves the
138same captcha in audio format.
139
140To serve a captcha as a downloadable file, the URL must be constructed in
141such a way as if the file to serve is in the "download" subdirectory:
142"/download/B9QTvDV1RXbVJ3Ac.wav".
143
144To reload captcha (get a different solution for the same captcha id), append
145"?reload=x" to URL, where x may be anything (for example, current time or a
146random number to make browsers refetch an image instead of loading it from
147cache).
148
149### func SetCustomStore
150
151	func SetCustomStore(s Store)
152	
153SetCustomStore sets custom storage for captchas, replacing the default
154memory store. This function must be called before generating any captchas.
155
156### func Verify
157
158	func Verify(id string, digits []byte) bool
159	
160Verify returns true if the given digits are the ones that were used to
161create the given captcha id.
162
163The function deletes the captcha with the given id from the internal
164storage, so that the same captcha can't be verified anymore.
165
166### func VerifyString
167
168	func VerifyString(id string, digits string) bool
169	
170VerifyString is like Verify, but accepts a string of digits.  It removes
171spaces and commas from the string, but any other characters, apart from
172digits and listed above, will cause the function to return false.
173
174### func WriteAudio
175
176	func WriteAudio(w io.Writer, id string) os.Error
177	
178WriteAudio writes WAV-encoded audio representation of the captcha with the
179given id.
180
181### func WriteImage
182
183	func WriteImage(w io.Writer, id string, width, height int) os.Error
184	
185WriteImage writes PNG-encoded image representation of the captcha with the
186given id. The image will have the given width and height.
187
188
189Types
190-----
191
192``` go
193type Audio struct {
194    // contains unexported fields
195}
196```
197
198
199### func NewAudio
200
201	func NewAudio(digits []byte) *Audio
202	
203NewImage returns a new audio captcha with the given digits, where each digit
204must be in range 0-9.
205
206### func (*Audio) EncodedLen
207
208	func (a *Audio) EncodedLen() int
209	
210EncodedLen returns the length of WAV-encoded audio captcha.
211
212### func (*Audio) WriteTo
213
214	func (a *Audio) WriteTo(w io.Writer) (n int64, err os.Error)
215	
216WriteTo writes captcha audio in WAVE format into the given io.Writer, and
217returns the number of bytes written and an error if any.
218
219``` go
220type Image struct {
221    *image.NRGBA
222    // contains unexported fields
223}
224```
225
226
227### func NewImage
228
229	func NewImage(digits []byte, width, height int) *Image
230	
231NewImage returns a new captcha image of the given width and height with the
232given digits, where each digit must be in range 0-9.
233
234### func (*Image) WriteTo
235
236	func (img *Image) WriteTo(w io.Writer) (int64, os.Error)
237	
238WriteTo writes captcha image in PNG format into the given writer.
239
240``` go
241type Store interface {
242    // Set sets the digits for the captcha id.
243    Set(id string, digits []byte)
244
245    // Get returns stored digits for the captcha id. Clear indicates
246    // whether the captcha must be deleted from the store.
247    Get(id string, clear bool) (digits []byte)
248}
249```
250
251An object implementing Store interface can be registered with SetCustomStore
252function to handle storage and retrieval of captcha ids and solutions for
253them, replacing the default memory store.
254
255It is the responsibility of an object to delete expired and used captchas
256when necessary (for example, the default memory store collects them in Set
257method after the certain amount of captchas has been stored.)
258
259### func NewMemoryStore
260
261	func NewMemoryStore(collectNum int, expiration int64) Store
262	
263NewMemoryStore returns a new standard memory store for captchas with the
264given collection threshold and expiration time in seconds. The returned
265store must be registered with SetCustomStore to replace the default one.
266
267
268Bugs
269----
270
271* [Not our bug] Google Chrome 10 plays unsigned 8-bit PCM WAVE
272audio on Mac with horrible distortions.  Issue:
273http://code.google.com/p/chromium/issues/detail?id=70730.
274This has been fixed, and version 12 will play them properly.
275
276* While Image conforms to io.WriterTo interface, its WriteTo
277method returns 0 instead of the actual bytes written because png.Encode
278doesn't report this.
279
280
281Subdirectories
282--------------
283
284* capgen
285* example
286* generate
287