doc: convert RELP specification to Markdown#293
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request converts the RELP specification document from HTML (doc/relp.html) to Markdown (doc/relp.md) and updates the Makefile accordingly. The review feedback focuses on correcting various typographical errors, spelling mistakes (such as 'ressources', 'intial', 'absued', and 'invokation'), grammatical inconsistencies, and an ABNF definition mismatch in the newly added Markdown file.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| ## DESCRIPTION OF THE RELP PROTOCOL | ||
|
|
||
| Relp uses a client-server model with (mostly fixed roles. The initiating part |
There was a problem hiding this comment.
There is an unmatched parenthesis in (mostly. It should be (mostly) or simply mostly.
| Relp uses a client-server model with (mostly fixed roles. The initiating part | |
| Relp uses a client-server model with (mostly) fixed roles. The initiating part |
| outstanding at a given time. The server may reply in any order. To conserve | ||
| ressources, the number of outstanding commands is limited by a window. Each |
There was a problem hiding this comment.
The word ressources is misspelled. It should be resources.
| outstanding at a given time. The server may reply in any order. To conserve | |
| ressources, the number of outstanding commands is limited by a window. Each | |
| outstanding at a given time. The server may reply in any order. To conserve | |
| resources, the number of outstanding commands is limited by a window. Each |
| timeouts a sessions where the client has not sent any data for an extended | ||
| period of time (this probably is a good thing to conserve server ressources). |
There was a problem hiding this comment.
Correct the grammatical error timeouts a sessions to timeouts a session (or times out a session) and the spelling of ressources to resources.
| timeouts a sessions where the client has not sent any data for an extended | |
| period of time (this probably is a good thing to conserve server ressources). | |
| timeouts a session where the client has not sent any data for an extended | |
| period of time (this probably is a good thing to conserve server resources). |
| RSP-HEADER = TXNR SP RSP-CODE [SP HUMANMSG] LF [CMDDATA] | ||
| RSP-CODE = 200 / 500 ; 200 is ok, all the rest currently erros | ||
| HUAMANMSG = *OCTET ; a human-readble message without LF in it |
There was a problem hiding this comment.
There is an inconsistency in the ABNF definition: RSP-HEADER references HUMANMSG, but the definition below it is spelled HUAMANMSG. Additionally, erros is a typo for errors, and human-readble is a typo for human-readable.
| RSP-HEADER = TXNR SP RSP-CODE [SP HUMANMSG] LF [CMDDATA] | |
| RSP-CODE = 200 / 500 ; 200 is ok, all the rest currently erros | |
| HUAMANMSG = *OCTET ; a human-readble message without LF in it | |
| RSP-HEADER = TXNR SP RSP-CODE [SP HUMANMSG] LF [CMDDATA] | |
| RSP-CODE = 200 / 500 ; 200 is ok, all the rest currently errors | |
| HUMANMSG = *OCTET ; a human-readable message without LF in it |
| server-closed connection even if the server does not send a "serverclose" | ||
| hint. In thus case, it must rely on the transport layer connection status. The | ||
| primary utility of "serverclose" is to enable the client to quickly detect a | ||
| server-closed connection, clean up ressources and go into termination (or | ||
| recovery code). |
There was a problem hiding this comment.
Correct the typos In thus case to In this case and ressources to resources.
| server-closed connection even if the server does not send a "serverclose" | |
| hint. In thus case, it must rely on the transport layer connection status. The | |
| primary utility of "serverclose" is to enable the client to quickly detect a | |
| server-closed connection, clean up ressources and go into termination (or | |
| recovery code). | |
| server-closed connection even if the server does not send a 'serverclose' | |
| hint. In this case, it must rely on the transport layer connection status. The | |
| primary utility of 'serverclose' is to enable the client to quickly detect a | |
| server-closed connection, clean up resources and go into termination (or | |
| recovery code). |
| I define this use case in support of [rsyslog](http://www.rsyslog.com) and | ||
| other possible clients which try to reduce ressource consumption. |
There was a problem hiding this comment.
The word ressource is misspelled. It should be resource.
| I define this use case in support of [rsyslog](http://www.rsyslog.com) and | |
| other possible clients which try to reduce ressource consumption. | |
| I define this use case in support of [rsyslog](http://www.rsyslog.com) and | |
| other possible clients which try to reduce resource consumption. |
| server sends the response packet. Thus, the tcp stacks receive buffer buffers | ||
| the server's response until the client has another message to send. Then, the | ||
| client first checks for any outstanding responses, processes them and then | ||
| send the new message. It is expected that in this scenario, each client |
There was a problem hiding this comment.
The word invokation is misspelled. It should be invocation.
| send the new message. It is expected that in this scenario, each client | |
| invocation will process the past response and send a new packet. The response |
| but by the next one. So we always have one outstanding response inside the OS | ||
| buffers. Now consider the server is shutting down the connection due to | ||
| timeout or due to the fact that it needs to shutdown itself (maybe even on an | ||
| urgent case, like power failure - the point is it can not wait). On next client |
There was a problem hiding this comment.
The word invokation is misspelled. It should be invocation.
| urgent case, like power failure - the point is it can not wait). On next client | |
| invocation, the client finds an outstanding response and processes it. Then, |
| urgent case, like power failure - the point is it can not wait). On next client | ||
| invokation, the client finds an outstanding response and processes it. Then, | ||
| it tries to send a new command. That will fail, because the connection has been | ||
| terminated. The usual session recovery logic is used to restablish the |
There was a problem hiding this comment.
The word restablish is misspelled. It should be re-establish or reestablish.
| terminated. The usual session recovery logic is used to restablish the | |
| terminated. The usual session recovery logic is used to re-establish the |
| case. As such, acks are potentially lost. This will lead to message duplication | ||
| as the client assumes that the frames unacked at time of force-close where not |
There was a problem hiding this comment.
The word where is misspelled/incorrectly used here. It should be were.
| case. As such, acks are potentially lost. This will lead to message duplication | |
| as the client assumes that the frames unacked at time of force-close where not | |
| as the client assumes that the frames unacked at time of force-close were not | |
| processed (there is no other safe assumption). Consequently, the client will |
1 participant
Summary
relp.mdinstead ofrelp.htmlCloses #271.
Validation
autoreconf -fi,./configure, andmake dist; the archive containsdoc/relp.mdanddoc/gfdl.htmlbasic-sessionbreak-vg.shin isolation against both upstreammasterand this branch; both passedThe full
make distcheckrun passed 28 tests, skipped 1, and hit one non-deterministic failure inbasic-sessionbreak-vg.sh; the failing test passed when rerun in isolation on both the unchanged base and this branch.AI assistance
This documentation conversion was prepared with AI assistance. The semantic-parity checks, GitHub rendering checks, build/distribution checks, and an independent diff review were completed before submission.
Summary by cubic
Converted the RELP protocol specification from HTML to GitHub-flavored Markdown and updated the build to distribute relp.md. Closes #271; preserves visible text, links, heading hierarchy, and code/preformatted examples for better GitHub rendering and maintenance.
Written for commit c2a9c58. Summary will update on new commits.