On this page:
3.4.1 Basic Combinators
stuffer/ c
3.4.2 Serialization
3.4.3 Base64 Encoding
3.4.4 GZip Compression
3.4.5 Key/ Value Storage
3.4.6 Hash-addressed Storage
hash/ c
3.4.7 HMAC-SHA1 Signing
3.4.8 Helpers

3.4 Stuffers

 (require web-server/stuffers)


  #lang web-server

module language provides serializable continuations. The serialization functionality is abstracted into stuffers that control how it operates. You can supply your own (built with these functions) when you write a stateless servlet.

3.4.1 Basic Combinators

 (require web-server/stuffers/stuffer)

(struct stuffer (in out))
  in : (any/c . -> . any/c)
  out : (any/c . -> . any/c)

A stuffer is essentially an invertible function captured in this structure. The following should hold:

  (out (in x)) = x
  (in (out x)) = x

(stuffer/c dom rng)  contract?
  dom : any/c
  rng : any/c

Constructs a contract for a stuffer where in has the contract (-> dom rng) and out has the contract (-> rng dom).

id-stuffer : (stuffer/c any/c any/c)

The identitiy stuffer.

(stuffer-compose g f)  (stuffer any/c any/c)
  g : (stuffer any/c any/c)
  f : (stuffer any/c any/c)

Composes f and g, i.e., applies f then g for in and g then f for out.

(stuffer-sequence f g)  (stuffer any/c any/c)
  f : (stuffer any/c any/c)
  g : (stuffer any/c any/c)

stuffer-compose with arguments swapped.

(stuffer-if c f)  (stuffer bytes? bytes?)
  c : (bytes? . -> . boolean?)
  f : (stuffer bytes? bytes?)

Creates a stuffer that stuffs with f if c is true on the input to in. Similarly, applies f during out if it was applied during in (which is recorded by prepending a byte.)

(stuffer-chain x ...)  stuffer?
  x : (or/c stuffer? (bytes? . -> . boolean?))

Applies stuffer-sequence and stuffer-if to successive tails of x.

3.4.2 Serialization

 (require web-server/stuffers/serialize)

serialize-stuffer : (stuffer/c serializable? bytes?)

A stuffer that uses serialize and write/bytes and deserialize and read/bytes.

3.4.3 Base64 Encoding

 (require web-server/stuffers/base64)

base64-stuffer : (stuffer/c bytes? bytes?)

A stuffer that uses base64-encode and base64-decode.

Useful for getting URL-safe bytes.

3.4.4 GZip Compression

 (require web-server/stuffers/gzip)

gzip-stuffer : (stuffer/c bytes? bytes?)

A stuffer that uses gzip/bytes and gunzip/bytes.

Warning: You should compose this with base64-stuffer to get URL-safe bytes.

3.4.5 Key/Value Storage

The web-server/stuffers/hash stuffers rely on a key/value store.

 (require web-server/stuffers/store)

(struct store (write read))
  write : (bytes? bytes? . -> . void)
  read : (bytes? . -> . bytes?)

The following should hold:

  (begin (write k v) (read k)) = v

(dir-store root)  store?
  root : path-string?

A store that stores key key’s value in a file located at

   (bytes->string/utf-8 key))

It should be easy to use this interface to create store for databases, like SQLite, CouchDB, or BerkeleyDB.

3.4.6 Hash-addressed Storage

 (require web-server/stuffers/hash)

hash/c : contract?

Equivalent to (-> bytes? bytes?).

(hash-stuffer H store)  (stuffer/c bytes? bytes?)
  H : hash/c
  store : store?

A content-addressed storage stuffer that stores input bytes, input, in store with the key (H input) and returns the key. Similarly, on out the original bytes are looked up.

(md5-stuffer root)  (stuffer/c bytes? bytes?)
  root : path-string?

Equivalent to (hash-stuffer md5 (dir-store root))

3.4.7 HMAC-SHA1 Signing

 (require web-server/stuffers/hmac-sha1)

(HMAC-SHA1 kb db)  bytes?
  kb : bytes?
  db : bytes?

Performs a HMAC-SHA1 calculation on db using kb as the key. The result is guaranteed to be 20 bytes. (You could curry this to use it with hash-stuffer, but there is little value in doing so over md5.)

(HMAC-SHA1-stuffer kb)  (stuffer/c bytes? bytes?)
  kb : bytes?

A stuffer that signs input using HMAC-SHA1 with kb as the key. The result of the stuffer is the hash prepended to the input data. When the stuffer is run in reverse, it checks if the first 20 bytes are the correct has for the rest of the data.

Warning: You should compose this with base64-stuffer to get URL-safe bytes.

Warning: Without explicit provision, it is possible for users to modify the continuations they are sent through the other stuffers. This stuffer allows the servlet to certify that stuffed data was truly generated by the servlet. Therefore, you should use this if you are not using the hash-stuffers.

Warning: This stuffer does not encrypt the data in anyway, so users can still observe the stuffed values.

3.4.8 Helpers

 (require web-server/lang/stuff-url)

(is-url-too-big? v)  boolean?
  v : bytes?

Determines if stuffing v into the current servlet’s URL would result in a URL that is too big for Internet Explorer. (IE only supports URLs up to 2048 characters.).

(make-default-stuffer root)  (stuffer/c serializable? bytes?)
  root : path-string?

Constructs a stuffer that serializes, then if the URL is too big, compresses (and base64-encodes), if the URL is still too big then it stores it in an MD5-indexed database rooted at root.

Equivalent to:

   (md5-stuffer root))

default-stuffer : (stuffer/c serializable? bytes?)

Equivalent to:

    (find-system-path 'home-dir)