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 with
 16the spoken solution (currently in English and Russian). 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``` go
 73const (
 74    // Standard width and height of a captcha image.
 75    StdWidth  = 240
 76    StdHeight = 80
 77)
 78```
 79
 80
 81Variables
 82---------
 83
 84``` go
 85var (
 86    ErrNotFound = os.NewError("captcha: id not found")
 87)
 88```
 89
 90
 91
 92Functions
 93---------
 94
 95### func New
 96
 97	func New() string
 98	
 99New creates a new captcha with the standard length, saves it in the internal
100storage and returns its id.
101
102### func NewLen
103
104	func NewLen(length int) (id string)
105	
106NewLen is just like New, but accepts length of a captcha solution as the
107argument.
108
109### func RandomDigits
110
111	func RandomDigits(length int) (b []byte)
112	
113RandomDigits returns a byte slice of the given length containing
114pseudorandom numbers in range 0-9. The slice can be used as a captcha
115solution.
116
117### func Reload
118
119	func Reload(id string) bool
120	
121Reload generates and remembers new digits for the given captcha id.  This
122function returns false if there is no captcha with the given id.
123
124After calling this function, the image or audio presented to a user must be
125refreshed to show the new captcha representation (WriteImage and WriteAudio
126will write the new one).
127
128### func Server
129
130	func Server(imgWidth, imgHeight int) http.Handler
131	
132Server returns a handler that serves HTTP requests with image or
133audio representations of captchas. Image dimensions are accepted as
134arguments. The server decides which captcha to serve based on the last URL
135path component: file name part must contain a captcha id, file extension —
136its format (PNG or WAV).
137
138For example, for file name "LBm5vMjHDtdUfaWYXiQX.png" it serves an image captcha
139with id "LBm5vMjHDtdUfaWYXiQX", and for "LBm5vMjHDtdUfaWYXiQX.wav" it serves the
140same captcha in audio format.
141
142To serve a captcha as a downloadable file, the URL must be constructed in
143such a way as if the file to serve is in the "download" subdirectory:
144"/download/LBm5vMjHDtdUfaWYXiQX.wav".
145
146To reload captcha (get a different solution for the same captcha id), append
147"?reload=x" to URL, where x may be anything (for example, current time or a
148random number to make browsers refetch an image instead of loading it from
149cache).
150
151By default, the Server serves audio in English language. To serve audio
152captcha in one of the other supported languages, append "lang" value, for
153example, "?lang=ru".
154
155### func SetCustomStore
156
157	func SetCustomStore(s Store)
158	
159SetCustomStore sets custom storage for captchas, replacing the default
160memory store. This function must be called before generating any captchas.
161
162### func Verify
163
164	func Verify(id string, digits []byte) bool
165	
166Verify returns true if the given digits are the ones that were used to
167create the given captcha id.
168
169The function deletes the captcha with the given id from the internal
170storage, so that the same captcha can't be verified anymore.
171
172### func VerifyString
173
174	func VerifyString(id string, digits string) bool
175	
176VerifyString is like Verify, but accepts a string of digits.  It removes
177spaces and commas from the string, but any other characters, apart from
178digits and listed above, will cause the function to return false.
179
180### func WriteAudio
181
182	func WriteAudio(w io.Writer, id string, lang string) os.Error
183	
184WriteAudio writes WAV-encoded audio representation of the captcha with the
185given id and the given language. If there are no sounds for the given
186language, English is used.
187
188### func WriteImage
189
190	func WriteImage(w io.Writer, id string, width, height int) os.Error
191	
192WriteImage writes PNG-encoded image representation of the captcha with the
193given id. The image will have the given width and height.
194
195
196Types
197-----
198
199``` go
200type Audio struct {
201    // contains unexported fields
202}
203```
204
205
206### func NewAudio
207
208	func NewAudio(digits []byte, lang string) *Audio
209	
210NewImage returns a new audio captcha with the given digits, where each digit
211must be in range 0-9. Digits are pronounced in the given language. If there
212are no sounds for the given language, English is used.
213
214### func (*Audio) EncodedLen
215
216	func (a *Audio) EncodedLen() int
217	
218EncodedLen returns the length of WAV-encoded audio captcha.
219
220### func (*Audio) WriteTo
221
222	func (a *Audio) WriteTo(w io.Writer) (n int64, err os.Error)
223	
224WriteTo writes captcha audio in WAVE format into the given io.Writer, and
225returns the number of bytes written and an error if any.
226
227``` go
228type Image struct {
229    *image.Paletted
230    // contains unexported fields
231}
232```
233
234
235### func NewImage
236
237	func NewImage(digits []byte, width, height int) *Image
238	
239NewImage returns a new captcha image of the given width and height with the
240given digits, where each digit must be in range 0-9.
241
242### func (*Image) WriteTo
243
244	func (m *Image) WriteTo(w io.Writer) (int64, os.Error)
245	
246WriteTo writes captcha image in PNG format into the given writer.
247
248``` go
249type Store interface {
250    // Set sets the digits for the captcha id.
251    Set(id string, digits []byte)
252
253    // Get returns stored digits for the captcha id. Clear indicates
254    // whether the captcha must be deleted from the store.
255    Get(id string, clear bool) (digits []byte)
256}
257```
258
259An object implementing Store interface can be registered with SetCustomStore
260function to handle storage and retrieval of captcha ids and solutions for
261them, replacing the default memory store.
262
263It is the responsibility of an object to delete expired and used captchas
264when necessary (for example, the default memory store collects them in Set
265method after the certain amount of captchas has been stored.)
266
267### func NewMemoryStore
268
269	func NewMemoryStore(collectNum int, expiration int64) Store
270	
271NewMemoryStore returns a new standard memory store for captchas with the
272given collection threshold and expiration time in seconds. The returned
273store must be registered with SetCustomStore to replace the default one.
274
275
276Bugs
277----
278
279* [Not our bug] Google Chrome 10 plays unsigned 8-bit PCM WAVE
280audio on Mac with horrible distortions.  Issue:
281http://code.google.com/p/chromium/issues/detail?id=70730.
282This has been fixed, and version 12 will play them properly.
283
284* While Image conforms to io.WriterTo interface, its WriteTo
285method returns 0 instead of the actual bytes written because png.Encode
286doesn't report this.
287
288
289Subdirectories
290--------------
291
292* capgen
293* example
294* generate