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