Re: documentation for (web ...)

[Andy Wingo]

Greets,

On Sat 22 Jan 2011 00:05, Neil Jerram <address@hidden> writes:

>>>>  -- Function: uri-decode str [#:charset]
>>>>      Percent-decode the given STR, according to CHARSET.
>
> I'm still not completely sure here.  What if STR contains normal
> characters as well as possible %XX sequences.  If I call uri-decode with
> #:encoding #f, how is each normal character mapped into the resulting
> bytevector?

>From RFC 3986 1.2.1:

   A URI is a sequence of characters from a very limited set: the
   letters of the basic Latin alphabet, digits, and a few special
   characters.

So for non-encoded chars, if the char->integer of the char is less than
128, then we just write the byte out; and otherwise signal an error.  I
think that means that the encoding has to be 7-bit ascii-compatible.

>> Or should we give brief descriptions of the meanings of all of these
>> headers as well? That might be a good idea too.
>
> No, I don't think that's needed.

I did end up doing that, but if it's too much text, we can think of ways
to compress it...

Speaking of which, Peter Bex's "intarweb" egg for chicken is a fairly
mature, well-documented piece of code that does pretty much the same
thing.  I only learned about it after I had done most of the work on
Guile's web stack, but it's still useful as a repo of good ideas, docs,
and interfaces:

  http://wiki.call-cc.org/eggref/4/intarweb?action=show

>>>> `transfer-encoding'

The current text is:

 -- HTTP Header: List transfer-encoding
     A list of transfer codings, expressed as key-value lists.  The only
     transfer coding defined by the specification is `chunked'.
          (parse-header 'transfer-encoding "chunked")
          => (chunked)

And actually that's a bug, it actually parses to ((chunked)).  I'll push
a fix.

> Hmm.  I still don't feel I completely understand this; but on the other
> hand it's too fiddly to me to want to go into more now.  I think I'll
> wait until I actually have to process something with these structures.

Yeah, it's not really a pleasant topic.  Hopefully this sleeping dog
will indeed lie.

>>>> `www-authenticate'
>>>>      A string.
>>>
>>> Obviously there's lots of substructure there (in WWW-Authenticate) that
>>> we just don't support yet.  Is there a clear compatibility story for
>>> if/when Guile is enhanced to parse that out?
>>>
>>> I guess yes; calling code will just need something like
>>>
>>>   (if (string? val)
>>>       ;; An older Guile that doesn't parse authentication fully.
>>>       (do-application-own-parsing)
>>>       ;; A newer Guile that does parse authentication.
>>>       (use-the-parsed-authentication-object))

So I did fix this one.  But the compatibility story for other headers is
that if the application is relying on the value of a header that is not
declared by Guile, the application should declare that headers, and rely
on its parsers, validators, and writers.

That way if Guile comes along later and defines a parser for Set-Cookie,
the application that depends on Set-Cookie doesn't have to change,
because it already defined its own parser.

>>   1) Works with other socket architectures (zeromq, particularly).
>
> I'm not familiar with that, but will take a look.

I really like the idea of mongrel2 -- http://mongrel2.org/home.
Mongrel2 is a web server that just parses the request, figures out where
to route the request, then forwards the request to some other process
via zeromq (zeromq.org).  Really seems like the Right Thing(TM) for a
web server to do.  A project for another day...

Thanks for all your helpful comments!

Andy
-- 
http://wingolog.org/