protocol handling spec?

[Avery Pennarun]

On Mon, Aug 09, 2004 at 10:29:47PM +0100, Dave Cridland wrote:

> >I think you're misunderstanding the difference between the jobs performed
> >by URIs and MIME types.  It's actually easy, and if you look at it the
> >right way, none of the examples you gave are special cases at all. 
>
> Any time someone says "It's actually easy", I always get suspicious.

When someone tries to tell me that a well-thought-out standard such as URI
is actually complicated and non-working, *I* get suspicious.  The sign of a
good design is that it's easy to explain.  I disagree with your arguments
against the essential simplicity, as follows.

> Yes, this is true. It's also far too generalized to be of any use:
> 
> // Universal URI API.
> typedef void * stuff_t;
> stuff_t * url_handler( url_t * u, stuff_t * stuff );
> // Note, may be called with NULL, may return NULL. Might have side-effects.

You think so?
	fd = open(path, flags);
	write(fd, buf, size);
	read(fd, buf, size);
	close(fd);

Does that look too simple and generalized to be of any use?  It shouldn't;
it's the Unix API.  (There are a few more details to worry about, but that's
also true of any URI API.  In the real world you can't always *just* have
the blob send/receive function, but you don't need *much* more for everyday
use.)

> IMAP folder contents do not have a MIME type.

Of course they do.  Maybe not a standardized one, but you could represent
these, for example, as an XML file with a particular schema, if that made
you happy.  I can guarantee you that if I ask KDE's URL retriever to get me
an IMAP folder, it will get me a document, and all documents have a MIME
type, whether standardized or not.

> MIME types describe a chunk of static data. IMAP folders are not static.

The web is also not static.  The contents of an IMAP folder at a given point
in time is a chunk of static data.  If I want the latest contents later,
that will also be a chunk of static data.  The various chunks of static data
that I get will all have MIME types.

> > - The returned blob, if any, gets displayed according to its MIME type.
> 
> What MIME type? And what's "displayed" mean?

Each URI scheme has its own way of determining what MIME type the retrieved
blob has.  HTTP and IMAP can make it explicit.  With ftp: or file: or smb:,
you have to cheat.

"Displayed" is a word I used here instead of the more accurate "operated
upon".  In a web browser, you tend to want to display things.  Anyway, for
any given MIME type there are different operations you might want to
perform.  You do these according to the MIME type, though, not the URI.

> >   > 'mailto' - [...]
> >
> >Sends a blob containing things like subject line, to address, etc. [...]
>
> Using my Trusty Hammer Of Metaphor Forcing, I can just about accept 
> this. However, my Trusty Hammer is not very big - considerably 
> smaller than the planet, in fact, and thus I tend to prefer making 
> the model fit the data rather than the other way around.

That's not very forced.  It even works fine with the nice generalized API
you proposed; I don't even need to add any API extensions.

	uri_handler("mailto:apenwarr at nit.ca", NULL);

And the mail gets sent.  Why should konqueror or Nautilus care *how* it got
sent?

> >> 'http' - [...]
> >
> >Sends a blob containing a method name (GET, PUT, POST, etc) and optional
> >POST or PUT data.  Retrieves a blob containing a status code, MIME type,
> >and data.
>
> This would appear to be the model that everything else is trying to 
> fit. I didn't need to use my Hammer once this time, although it 
> twitched somewhat when I wondered where the method name and payload 
> was coming from.

In fact, http *is* forced into this model, precisely because GET, PUT, POST,
etc are actually part of the resource.  When I do "PUT /foo", I mean
something different than "GET /foo" or "POST /foo".  Each of these three
might return a different "blob".

In the general API you proposed, you worked around this by defaulting to
"GET", or else, when relevant, explicitly including "PUT" or "POST" as part
of your "stuff" blob.  You're very clever.  I'm impressed.

> >> 'imap' - [...] 
> >Sends a blob containing new message contents or nothing.  Retrieves a
> >blob containing folder contents, etc.
>
> Erm, hopefully not. IMAP folders are not static. The messages are, 
> and their parts are, but folders change. And please, don't ever 
> implement some bizarre URI handler that hands back the entire 
> contents of a folder. That would frankly be horrible, given that it's 
> very unlikely the user wants to see *all* of it.

Sorry, KDE already implemented the bizarre URI handler you speak of - at
least, it hands back the *listing* of the contents of your folder, which is
of course exactly what you want.  Then you can request (or not, as you
wish), each individual message separately.  And the URI handler itself can
handle caching.

The API you proposed is nice and simple, but if it were me, I might want to
add a special function for specifically composing/decomposing lists.  More
than just imap: will want to create lists of objects that I can parse and
navigate in a general way.  Of course, HTML and XML are both reasonable(*)
ways of creating general types of lists.

> >> 'acap' - [...]
> >
> >Sends/receives blobs containing configuration data.  The data may have a
> >specific MIME type determining what should be done with it.
>
> Actually, almost certainly not. It rarely has a MIME type in the case 
> of ACAP. In fact, I would guess that most of the time, the 'sensible' 
> action with most ACAP URIs would be to record the URI in some 
> attribute of a newly created entry in some ACAP dataset. Or more 
> likely still, ask the user.

I assume that ACAP items are either text/plain or something similar.  That's
a MIME type.  What's the problem?

If I type acap:something into konqueror, I'd expect it to display it by
default using the default text/plain viewer, unless it's some other data
type.  (If the result is an application/x-acap-object or something, then
maybe it would ask me to merge into some dataset or something.)

> Tell me how 'telnet' fits in with your plans?

I'm glad you asked.  Your proposed API works fine with this too, in the same
way that mailto: does.

	uri_handler("telnet:hostname", NULL);

> I do, however, agree that *some* instances of *some* URI schemes 
> *may* be treated essentially as filenames.

No!  Don't treat them as filenames!  I never said to treat them as
filenames!  Treat them as parameters into some standard API, the URI
Handling API.

(BTW, a more general URI-type mechanism is the "moniker", which is simply a
mapping of strings into objects.  When you request a moniker for a
particular factory, it'll give you a corresponding object that implements a
particular API.  A URI is a particular kind of moniker that returns objects
implementing the URI API.)

> Others behave much more like commands.

"Send this blob, do this, and receive another blob" is a superset of "do
this."

> Being able to specify an individual message in a shared folder across IRC
> is, however, something I keep on trying to do [...]
> 
> If I were to click on that, I'd basically expect my mail client to pop
> open, open that folder, and finally find your message, and display it.
> (Actually, it can, [...]

Erm, so it already works, and you're still complaining?  In that case, your
problems are beyond my ability to solve.

> but that's an aside - I expect this to happen everywhere, not just on my
> carefully mutilated system here.)

So get the gnome/kde maintainers to accept your mutilations into the
standard distribution.  It seems clear that their API is already quite good
enough to do what you want; you just want it to be the default.  More power
to you.

> That's the body of your message. It does have a natural, unforced, 
> no-hammer-required MIME type, of 'text/plain; charset="us-ascii"', in 
> fact.

The MIME type of an email message retrieved from any URI, including imap:,
should be message/rfc822.  When you display such a message, you should
expect it to pop up in some sort of "normal" mail reading program or
component, not just a text viewer.  Of course, you could also configure your
"default viewer" for that type of object to be a text viewer, since it
happens to be a text file.

> I would, however, get annoyed if I couldn't, when in a word processor,
> import your message text by specifying that URI.

This is why your IMAP client is the URI handler, and your mail reader is the
MIME handler.

Have fun,

Avery

(*) For very generous interpretations of the word "reasonable."