cURL / Mailing Lists / curl-library / Single Mail


Re: adding a protocol to (lib)curl?

From: Daniel Stenberg <>
Date: Wed, 9 Jan 2013 22:50:24 +0100 (CET)

On Wed, 9 Jan 2013, Jens Staal wrote:

> - Would the strategy I thought out even work? Any pro tips?

This is indeed an awesome question that most probably deserves a complete
separate document that is missing so far, but I'll start here and give you the
first lesson and then see how we continue...

First, some basic descriptions of some internal design concepts is found in
docs/INTERNALS. It isn't much but it might explain at least some parts.

0 - post your patches/questions often and early to get feedback and guidelines
early on before you make any major deviations from the path of the righteous!

1 - You need to implement protocols that are send or receive oriented, so if
your protocol is more fancy than just data going in either or both directions
then it isn't suitable for libcurl. Also, it really needs to use TCP or as an
exception UDP. If it uses more than one connection (like FTP) you're up for a
challange and a fair degree of pain.

2 - You need to be able to specify the target or source as a URL

3 - Once the above is sorted, you create lib/newprotocol.c and you declare a
'struct Curl_handler' in there to declare how the "regular" transfer engine
will call your protocol-specific parts. Then you implement those functions.

4 - Insert your newly created struct from (3) in the array protocols[] at the
top of lib/url.c to make it activated.

5 - if your protocol needs special CURLOPT_ options, you must add them.

6 - Write your test server in tests/server

7 - Adapt tests/ to be able to start your new test server for your
new protocol

8 - Add a bunch of new test cases in tests/data/test[num] so that you can
verify that your work is actually functional in the way it is supposed to be.

9 - Add the protocol and things to the documentation. Write a few examples to
docs/examples/ in case your protocol has special things to consider.

10 - if the protocol relies on a third-party library for anything, you also
need to adjust the script to detect and use it properly at build

... there are some more minor things to do, but I don't think I need to
mention them here since they'll be obvious or otherwise small enough anyway so
that if you reach this point those won't be problematic!

> - how "invasive" would adding a protocol be in curl? Since I am a total
> amateur, a too complex integration process would probably be above my
> competence level.

It really depends on the protocol. Compare how lib/gopher.c is dead simple
while lib/ftp.c or lib/ssh.c are very complicated.

Everything in libcurl is implemented non-blocking interally so for most
non-trivial protocols you must be prepared to write state-machines.

> - In the (unlikely) event that I actually succeeded, would upstream be
> interested? I am aware that it would most likely be limited to "fringe use
> cases", but there are uses for the 9P protocol, especially in communications
> between virtual machines and hosts.

I can't say that I've been waiting for this protocol. I didn't even know it
existed before your mail. This said, I won't exclude the possibility that some
people actually would find it useful. It would need to be made build-time
conditional anyway so if the effects of the code is otherwise manageable I
don't think I would object to getting it merged.

I will of course also listen to feedback and comments from others on this
subject - and in every step along the way. And I will of course also do my
best in helping you out to succeed with your mission!

Good luck!

(Surely this leaves no questions at all? :-))

List admin:
Received on 2013-01-09