1# Adding a new protocol? 2 3Every once in a while someone comes up with the idea of adding support for yet 4another protocol to curl. After all, curl already supports 25 something 5protocols and it is the Internet transfer machine for the world. 6 7In the curl project we love protocols and we love supporting many protocols 8and do it well. 9 10So how do you proceed to add a new protocol and what are the requirements? 11 12## No fixed set of requirements 13 14This document is an attempt to describe things to consider. There is no 15checklist of the twenty-seven things you need to cross off. We view the entire 16effort as a whole and then judge if it seems to be the right thing - for 17now. The more things that look right, fit our patterns and are done in ways 18that align with our thinking, the better are the chances that we will agree 19that supporting this protocol is a grand idea. 20 21## Mutual benefit is preferred 22 23curl is not here for your protocol. Your protocol is not here for curl. The 24best cooperation and end result occur when all involved parties mutually see 25and agree that supporting this protocol in curl would be good for everyone. 26Heck, for the world! 27 28Consider "selling us" the idea that we need an implementation merged in curl, 29to be fairly important. *Why* do we want curl to support this new protocol? 30 31## Protocol requirements 32 33### Client-side 34 35The protocol implementation is for a client's side of a "communication 36session". 37 38### Transfer oriented 39 40The protocol itself should be focused on *transfers*. Be it uploads or 41downloads or both. It should at least be possible to view the transfers as 42such, like we can view reading emails over POP3 as a download and sending 43emails over SMTP as an upload. 44 45If you cannot even shoehorn the protocol into a transfer focused view, then 46you are up for a tough argument. 47 48### URL 49 50There should be a documented URL format. If there is an RFC for it there is no 51question about it but the syntax doesn't have to be a published RFC. It could 52be enough if it is already in use by other implementations. 53 54If you make up the syntax just in order to be able to propose it to curl, then 55you are in a bad place. URLs are designed and defined for interoperability. 56There should at least be a good chance that other clients and servers can be 57implemented supporting the same URL syntax and work the same or similar way. 58 59URLs work on registered 'schemes'. There is a register of [all officially 60recognized 61schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml). If 62your protocol is not in there, is it really a protocol we want? 63 64### Wide and public use 65 66The protocol shall already be used or have an expectation of getting used 67widely. Experimental protocols are better off worked on in experiments first, 68to prove themselves before they are adopted by curl. 69 70## Code 71 72Of course the code needs to be written, provided, licensed agreeably and it 73should follow our code guidelines and review comments have to be dealt with. 74If the implementation needs third party code, that third party code should not 75have noticeably lesser standards than the curl project itself. 76 77## Tests 78 79As much of the protocol implementation as possible needs to be verified by 80curl test cases. We must have the implementation get tested by CI jobs, 81torture tests and more. 82 83We've experienced many times in the past how new implementations were brought 84to curl and immediately once the code had been merged, the originator vanished 85from the face of the earth. That is fine, but we need to take the necessary 86precautions so when it happens we are still fine. 87 88Our test infrastructure is powerful enough to test just about every possible 89protocol - but it might require a bit of an effort to make it happen. 90 91## Documentation 92 93We cannot assume that users are particularly familiar with specific details 94and peculiarities of the protocol. It needs documentation. 95 96Maybe it even needs some internal documentation so that the developers who 97will try to debug something five years from now can figure out functionality a 98little easier! 99 100The protocol specification itself should be freely available without requiring 101any NDA or similar. 102 103## Don't compare 104 105We are constantly raising the bar and we are constantly improving the 106project. A lot of things we did in the past would not be acceptable if done 107today. Therefore, you might be tempted to use shortcuts or "hacks" you can 108spot other - existing - protocol implementations have used, but there is 109nothing to gain from that. The bar has been raised. Former "cheats" won't be 110tolerated anymore. 111