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