diff --git a/.gitignore b/.gitignore index 894a44c..b16f2e0 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ __pycache__/ *.so # Distribution / packaging +.build/ .Python build/ develop-eggs/ diff --git a/.static/basic.css b/.static/basic.css new file mode 100644 index 0000000..ba50ada --- /dev/null +++ b/.static/basic.css @@ -0,0 +1,830 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 450px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +div.code-block-caption { + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +div.code-block-caption + div > div.highlight > pre { + margin-top: 0; +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + padding: 1em 1em 0; +} + +div.literal-block-wrapper div.highlight { + margin: 0; +} + +code.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; + border-style: none; + padding: 0; +} + +code.descclassname { + background-color: transparent; + border-style: none; + padding: 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; + border-style: none; + padding: 0; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: relative; + left: 0px; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} + +/* -- My additions ---------------------------------------------------------- */ + +div.admonition { + color: black; + background: #eeffcc url(dialog-topic.png) no-repeat 10px 8px; + border: 2px solid #aacc99; + border-left-style: none; + border-right-style: none; + padding: 10px 20px 0px 60px; +} + +div.todo { + color: black; + border: 2px solid #7a9eec; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; + background: #e1ecfe url(dialog-note.png) no-repeat 10px 8px; +} + +div.note { + color: black; + border: 2px solid #7a9eec; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; + background: #e1ecfe url(dialog-note.png) no-repeat 10px 8px; +} + +div.danger { + color: black; + border: 2px solid #fbc2c4; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; + background: #fbe3e4 url(dialog-note.png) no-repeat 10px 8px; +} + +div.attention { + color: black; + border: 2px solid #ffd324; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; + background: #fff6bf url(dialog-note.png) no-repeat 10px 8px; +} + +div.caution { + color: black; + border: 2px solid #ffd324; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; + background: #fff6bf url(dialog-warning.png) no-repeat 10px 8px; +} + +div.important { + color: black; + background: #fbe3e4 url(dialog-seealso.png) no-repeat 10px 8px; + border: 2px solid #fbc2c4; + border-left-style: none; + border-right-style: none; + padding: 10px 20px 0px 60px; +} + +div.seealso { + color: black; + background: #fff6bf url(dialog-seealso.png) no-repeat 10px 8px; + border: 2px solid #ffd324; + border-left-style: none; + border-right-style: none; + padding: 10px 20px 0px 60px; +} + +div.hint, div.tip, { + color: black; + background: #eeffcc url(dialog-topic.png) no-repeat 10px 8px; + border: 2px solid #aacc99; + border-left-style: none; + border-right-style: none; + padding: 10px 20px 0px 60px; +} + +div.warning, div.error { + color: black; + background: #fbe3e4 url(dialog-warning.png) no-repeat 10px 8px; + border: 2px solid #fbc2c4; + border-right-style: none; + border-left-style: none; + padding: 10px 20px 0px 60px; +} + +p { + text-align: justify; + padding-bottom: 5px; +} + +h1 { + background: #fff6bf; + border: 2px solid #ffd324; + border-left-style: none; + border-right-style: none; + padding: 10px 10px 10px 10px; + text-align: center; +} + +h2 { + /* background: #eeffcc; */ + border: 2px solid #aacc99; + border-left-style: none; + border-right-style: none; + border-top-style: none; + padding: 10px 0px 0px 0px; + /* text-align: center; */ +} + +h3 { + /* background: #eeffcc; */ + border: 1px solid #7a9eec; + border-left-style: none; + border-right-style: none; + border-top-style: none; + padding: 0; + /* text-align: center; */ +} + +h4 { + background: #eeffcc; + /* border: 1px solid #aacc99; */ + border-left-style: none; + border-right-style: none; + border-top-style: none; + padding: 5px 5px 5px 5px; + /* text-align: center; */ +} + +cite { + -webkit-border-radius: 3px; + -moz-border-radius: 3px; + border-radius: 3px; + border: 1px solid #e1e1e8; + background: #f7f7f9; + margin: 0 0 10px; + padding: 0 5px 0 5px; + font-size: 13px; + font-style: italic; +} + +.program { + -webkit-border-radius: 3px; + -moz-border-radius: 3px; + border-radius: 3px; + border: 1px solid #e1e1e8; + background: #f7f7f9; + margin: 0 0 10px; + padding: 0 5px 0 5px; + font-size: 13px; +} diff --git a/.static/by-sa.svg b/.static/by-sa.svg new file mode 100644 index 0000000..f850297 --- /dev/null +++ b/.static/by-sa.svg @@ -0,0 +1,199 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.static/dialog-note.png b/.static/dialog-note.png new file mode 100644 index 0000000..263fbd5 Binary files /dev/null and b/.static/dialog-note.png differ diff --git a/.static/dialog-seealso.png b/.static/dialog-seealso.png new file mode 100644 index 0000000..3eb7b05 Binary files /dev/null and b/.static/dialog-seealso.png differ diff --git a/.static/dialog-topic.png b/.static/dialog-topic.png new file mode 100644 index 0000000..2ac5747 Binary files /dev/null and b/.static/dialog-topic.png differ diff --git a/.static/dialog-warning.png b/.static/dialog-warning.png new file mode 100644 index 0000000..7233d45 Binary files /dev/null and b/.static/dialog-warning.png differ diff --git a/LICENSE.TXT b/LICENSE.TXT new file mode 100644 index 0000000..67faf14 --- /dev/null +++ b/LICENSE.TXT @@ -0,0 +1,427 @@ +Creative Commons Attribution Share Alike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..059b929 --- /dev/null +++ b/Makefile @@ -0,0 +1,75 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf .build/* + +html: + mkdir -p .build/html .build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ./docs + @echo + @echo "Build finished. The HTML pages are in ./docs." + +pickle: + mkdir -p .build/pickle .build/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +web: pickle + +json: + mkdir -p .build/json .build/doctrees + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + mkdir -p .build/htmlhelp .build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in .build/htmlhelp." + +latex: + mkdir -p .build/latex .build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex + @echo + @echo "Build finished; the LaTeX files are in .build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p .build/changes .build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes + @echo + @echo "The overview file is in .build/changes." + +linkcheck: + mkdir -p .build/linkcheck .build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in .build/linkcheck/output.txt." diff --git a/README.md b/README.md index 83fcb3a..c9ee945 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,13 @@ # Butler -Firebird Butler repository for specifications, descriptions and other project-wide documents + +Firebird Butler repository for specifications, descriptions and other project-wide documents in their source formats. The primary purpose is to collect specifications for APIs, file formats, wire protocols, and processes. + +The change process is C4: http://firebird-butler.rtfd.io/rfc/1/C4.html with a few modifications: + +- A specification is created and modified by pull requests according to C4. +- Each specification has an editor who publishes the RFC to Butler repository as needed. +- Specification life-cycle SHOULD follow the life-cycle defined in COSS: http://firebird-butler.rtfd.io/rfc/2/COSS.html +- Non-cosmetic changes are allowed only on Raw and Draft specifications. + +All published specifications and other related documents in HTML and other readable formats are available at http://firebird-butler.rtfd.io + diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..a52872b --- /dev/null +++ b/conf.py @@ -0,0 +1,266 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import sphinx_bootstrap_theme + +# -- Project information ----------------------------------------------------- + +project = u'Firebird Butler' +copyright = u'2018, Firebird Butler Project, CC BY-SA 4.0' +author = u'Pavel Cisar' + +# The short X.Y version +version = u'1.0' +# The full version, including alpha/beta/rc tags +release = u'1.0' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.githubpages', + 'sphinx.ext.todo', + 'aafigure.sphinxext' +] + +todo_include_todos = True +todo_link_only = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ['.rst','.spec'] + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [u'.build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +#html_theme = 'alabaster' +html_theme = "bootstrap" +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + +html_theme_options = { + # Navigation bar title. (Default: ``project`` value) + #'navbar_title': "Firebird Butler", + + # Tab name for entire site. (Default: "Site") + 'navbar_site_name': "Site content", + + # A list of tuples containing pages or urls to link to. + # Valid tuples should be in the following forms: + # (name, page) # a link to a page + # (name, "/aa/bb", 1) # a link to an arbitrary relative url + # (name, "http://example.com", True) # arbitrary absolute url + # Note the "1" or "True" value above as the third argument to indicate + # an arbitrary url. + 'navbar_links': [ + ("Introduction", "introduction"), + ("RFCs", "specifications"), + ("Project", "organization"), + # ("Index", "genindex"), + ], + + # Render the next and previous page links in navbar. (Default: true) + 'navbar_sidebarrel': False, + + # Render the current pages TOC in the navbar. (Default: true) + #'navbar_pagenav': True, + + # Tab name for the current pages TOC. (Default: "Page") + #'navbar_pagenav_name': "Page", + + # Global TOC depth for "site" navbar tab. (Default: 1) + # Switching to -1 shows all levels. + 'globaltoc_depth': 3, + + # Include hidden TOCs in Site navbar? + # + # Note: If this is "false", you cannot have mixed ``:hidden:`` and + # non-hidden ``toctree`` directives in the same page, or else the build + # will break. + # + # Values: "true" (default) or "false" + 'globaltoc_includehidden': "true", + + # HTML navbar class (Default: "navbar") to attach to
element. + # For black navbar, do "navbar navbar-inverse" + 'navbar_class': "navbar navbar-inverse", + + # Fix navigation bar to top of page? + # Values: "true" (default) or "false" + 'navbar_fixed_top': "true", + + # Location of link to source. + # Options are "nav" (default), "footer" or anything else to exclude. + #'source_link_position': "none", + 'source_link_position': "nav", + + # Bootswatch (http://bootswatch.com/) theme. + # + # Options are nothing (default) or the name of a valid theme + # such as "cosmo" or "sandstone". + # + # The set of valid themes depend on the version of Bootstrap + # that's used (the next config option). + # + # Currently, the supported themes are: + # - Bootstrap 2: https://bootswatch.com/2 + # - Bootstrap 3: https://bootswatch.com/3 + #'bootswatch_theme': "united", # cerulean, flatly, lumen, materia, united, yeti + 'bootswatch_theme': "cerulean", + + # Choose Bootstrap version. + # Values: "3" (default) or "2" (in quotes) + 'bootstrap_version': "2", +} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'FirebirdButlerdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'FirebirdButler.tex', u'Firebird Butler Documentation', + u'Pavel Cisar', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'firebirdbutler', u'Firebird Butler Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'FirebirdButler', u'Firebird Butler Documentation', + author, 'FirebirdButler', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..802815a --- /dev/null +++ b/index.rst @@ -0,0 +1,60 @@ + +################### +The Firebird Butler +################### + +The Firebird Butler is a separate division under `Firebird Project`_. The purpose of this sub-project is to develop and provide solutions to various Firebird-related challenges faced by Firebird administrators and application developers, that are not (for practical reasons) addressed by the core Firebird distribution. + +The **primary aim** of the sub-project is to create a development **platform** and a **set of basic solutions** to manage Firebird installations of **any** size, structure and complexity - with an emphasis on large corporate installations. However, the scope and ambitions of the Firebird Butler project are much broader, as we would like initiate development of the entire open source ecosystem of projects and other products, including commercial ones, in various languages. Projects could encompass not just the new services, but alternative implementations of the standard services as well. Moreover, the :ref:`butler-platform-intro` should become a solid foundation for development of any applications that use Service Oriented Architecture and messaging. + +For a closer look at the project goals and strategies, please read the :doc:`introduction`. + +.. + image:: butler-rings.png + :alt: Firebird Project structure + :scale: 100% + :align: center + +.. toctree:: + :maxdepth: 1 + :includehidden: + + +.. toctree:: + :maxdepth: 1 + :hidden: + + introduction + specifications + organization + + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + +.. _IBPhoenix: http://www.ibphoenix.com +.. _Firebird: http://www.firebirdsql.org +.. _Firebird Project: http://www.firebirdsql.org diff --git a/introduction.rst b/introduction.rst new file mode 100644 index 0000000..2722a3e --- /dev/null +++ b/introduction.rst @@ -0,0 +1,210 @@ +############################### +Introduction to Firebird Butler +############################### + + +The main ideas behind the project +================================= + +Itching to scratch +------------------ + +Managing IT infrastructure is basically a simple, two-component problem. One component is early detection of disaster and recovery from such events. The second component is a control system to maintain the operational parameters of the IT system within required limits. Both components should work in synergy and both involve parts that either measure various parameters, process or evaluate the measured values, or execute actions according to defined logic or upon human intervention. + +However, in practice it's a very challenging problem. Mostly because the requirements for each deployment are very diverse, and evolving over time. The second pitfall is the tools to help you solve this riddle. There are too many, and none of them is a silver bullet that solves everything. Also, you will soon find that the more one of the components can do, the more complex it is, and thus more prone to errors or hidden problems. You will also often find yourself in a straitjacket, where a product does 70%-98% of what you need, but the remaining is astonishingly hard to achieve if not simply impossible. So you will always end with either incomplete solution, or a mash-up solution and integration issues of various degree and severity. + +Managing Firebird deployments is no different in this regard. The sole difference is that the range of tools available specifically for this task is very small, and their help ends at the boundary of Firebird-related issues. But Firebird is only a (small) part of the wider picture, especially for the IT staff that has to manage a network of semi-automated production factories spread over several countries (to name at least one real-world example). + +The sad truth is, that you will always end up with a more or less custom solution (you at least have to hack together all required parts). And the more you do yourself, the more effective and reliable the final solution becomes. + +.. admonition:: Conclusion + + The truth at the very bottom of this problem is, that we don't really need a ready-to-use final solution (a *Golden Product*) - we actually need a **Solution Construction Kit**. + +The road to solution +-------------------- + +One of the key values on which the Firebird Project is built is the preservation of the philosophy inherited (through InterBase) from Borland, which can be described as *"clever engineering"*. One of the many examples of the realization of this philosophy was Borland Delphi, and the way it revolutionized the development of applications using components. While the concept was not completely new, the way it was used and implemented was clever and innovative. The Delphi Component Library was (and still is) a great example of a solid *"Solution Construction Kit"*. The Butler project builds on this basic idea but tries to translate it into the context of modern times. + +The IT world has changed a lot since 1995 when Delphi first appeared. Multi-platform, multi-device, distributed, scalability - those are the key words today. Today we build systems with such high levels of complexity, processing such astonishing amounts of data, that we have had to resort to AI and adaptive self-learning systems to cope with the issues raised. Almost everything is interconnected, and what is not yet soon will be. Today's components are no longer just classes but whole applications or systems connected through web technologies. The software component's paradigm has transformed itself into a service-oriented and messaging architecture. Unfortunately, due to stormy development, two unpleasant things happened. First, linking services using web technologies (primarily HTTP, JSON, etc.) was the result of giving priority to a path of lesser resistance rather than the effectiveness of these technologies. This has led to the tearing of the worlds of large and small software components. So now we have separate "component systems" for small solutions and the big ones, with no easy way to bridge the gap. + +.. admonition:: Our answer + + **The Firebird "Butler" Project** is a **serious** attempt to address this problem - in line with the Firebird's scalability doctrine **"from embedded to enterprise".** + + So, once again in Firebird's history [1]_, **We Boldly Go Where No Man Has Gone Before**. + +.. note:: + + The **Firebird Butler Development Platform** (a multi-platform library core similar to TComponent+TModule from Delphi VCL) is the *heart* of the Butler Project. The second layer built on top of it is the **Firebird Butler Service Library**, which is a *repository* of various (mostly Firebird-related) services. The outer layer is the **Firebird Butler** itself (*the product*), which should be a distribution (or set of purpose-tailored distributions) for direct deployment. + +| + +.. _butler-platform-intro: + +Firebird Butler Development Platform +==================================== + +In Delphi, the VCL components interact through direct method calls (connected to `event` attributes). Other systems (like Qt) use slightly different connection mechanisms, but the principle remains the same. The connection between components is predominantly stable, calls are synchronous, and predominantly stateful. The world of distributed services uses mostly unstable TCP/IP connections and stateless calls that are often asynchronous. + +So, is it even possible to bridge the gap between the worlds of small, in-process components and big, distributed ones? The answer is YES, if the focus is on a technical solution that subsumes the key properties for each and can easily live in both worlds. + +Let's look at the key properties closely. + +Direct method calls vs. TCP/IP +---------------------------------- + +Direct method calls are most effective, but while they are easy within single thread, they are impossible between threads or processes. The closest thing to it that you can do is remote procedure calling (RPC). Although RPC is easy today, it's also a killer of performance and scalability, especially when it is synchronous. + +Raw TCP/IP communication is easy today, and the same applies for using it in the context of web-related technologies (HTTP etc.). But using it for communication between threads (or even between objects in a single thread) is cumbersome and not very effective. The advantage is that you can easily go asynchronous. + +So it's clear that if you want scaleable solution, you have to give up the direct method calls, and resort to sending messages. However, you would need a message delivery system that is equally efficient for in-process, inter-process and network communication. In such a case the loss of direct calls may be an advantage rather than an obstacle (you can do more reliable parallel execution this way, even within a single thread). + +.. admonition:: Our approach + + The Butler Project chose ZeroMQ_ as the core solution for messaging. More about it later. + +Tight vs. loose coupling +------------------------ + +In a distributed environment, connecting between components via signals or event attributes and calling methods directly is equivalent to a stable TCP/IP connection - the connection is always present and open and you can always make a call. Tight coupling between connected components enables the most effective ways to do things. Doing the same with TCP/IP within single application is easy, since the connection can is unlikely break by itself. However, it is not so simple for connections between processes or over a network - they can break any time. Because nodes can disappear from the network, it's not always possible to achieve tight coupling efficiently and reliably over a network. That is why network services mostly use stateless protocols and communication. In the current state of affairs, the services are loosely coupled when integrated using some Service Integration Solution, such as Zato_, or by direct communication between the services. + +ain truth, using loose coupling is a hard tradeoff. It makes no sense to stick to it for deployments on a single computer nor for small or reliable corporate networks. It's a "better" solution only for integrations over unreliable or external sources, or with services that can't do better. These integration solutions merely opt for implementation simplicity over effectiveness, providing classic examples of one-size-fits-all syndrome gone wrong. + +.. admonition:: Our approach + + Our Firebird Butler Development Platform will allow the creation of services with **both** tight and loose integration, with preference for tightness. + + The **Firebird Butler product** will be basically an application. A LEGO-style application where you can stick various building blocks together in various ways, even distributed over a network, but it could be still viewed as single application/system. With both tight and loose coupling supported, it should be possible to have simplified builds for single execution as well as distributed builds encompassing a set of separate processes running on several nodes of the network. + +Synchronous vs. asynchronous +---------------------------- + +Synchronous communication is easier, but doesn't scale well. To perform complex processing of large amounts of data effectively, it's necessary to utilize CPU and other resources as much as possible, typically with parallel and/or asynchronous processing. However, there are many ways how to go parallel and asynchronous, and each style has its own strong and weak points. Also, each programming language has it's own specific way to do it. + +.. admonition:: Our approach + + The basis of the Firebird Butler Development Platform design is asynchronous communication between Butler Services, but without strictly defining its exact implementation. Various Butler Platform implementations could offer various (and even multiple) strategies for implementing Butler Services. However, services implemented in different ways and languages should be still able to interact with one another. + +ZeroMQ +---------- + +ZeroMQ is an elegant, small yet powerful library that handles the messaging fundamentals while allowing users to build various messaging architectures. The interface is based on the Berkeley sockets API, with `additional functionality `_. + +It provides services and patterns to do brokered or broker-less systems, sync and async messaging, various request/reply conversations, push/pull pipes, publisher/subscriber multicasts, workload pipelines, authentication, CURVE security, and various protocols (tcp, ipc, inproc, pgm/epgm, vmci). It significantly simplifies the development of viable custom systems with load balancing, high availability or reliability features, dynamic mashups, cloud architectures etc. It does not do these things for you, as other systems try to do, but you can do it yourself reliably without too much effort, in a way and to the extent that fits your needs. And as a cherry on top, ZeroMQ helps with reliable multi-thread applications using inproc sockets for fast and safe pipelines, or multi-process ones with ipc sockets. + +Of course it's not perfect. It will have limits, issues and dark corners like any piece of software out there, but we think that it provides everything we would need at a level that is good enough. + +You can learn more about ZeroMQ_ from the excellent ZGuide_, that includes many `examples in about 30 programming languages `_. + +ZeroMQ comes with the low-level C API. High-level bindings exist in 40+ languages including `Python `_, `Delphi `_, `FreePascal `_, Java, PHP, Ruby, C, C++, C#, Erlang, Perl, and `more `_. It also comes in a pure Java stack called JeroMQ_, and a pure C# stack called NetMQ_. These are both official projects and supported by the ZeroMQ community. + +Some organizations that we know use it are: AT&T, Cisco, EA, Los Alamos Labs, NASA, Weta Digital, Zynga, Spotify, Samsung Electronics, IBM, Microsoft, and CERN. + +Platform specification +---------------------- + +the Firebird Butler Development Platform defines basic features of Butler Services and messaging protocols. For example, it describes the following: + +- service registration and discovery +- communication negotiation (security, protocol version, communication channels, data format, sync/async patterns etc.) +- feature and configuration discovery +- service control +- message exchange methods (request/reply, push/pull, produce/subscribe etc.) + +The specification DOES NOT describe how individual services should do their jobs. For example if you are looking to create a service that does database backups, the specification defines how one should find it, connect to it, negotiate communication details (common patterns), discover its features, exchange messages, error handling and codes, some common messaging patterns like presence verification (ping), addressing, control messages etc. But what messages, data and formats your service uses to do its job, what features it would have and how it would do its work is up to you. You can create a dumb backup service that is just a thin wrapper around the backup provided by Firebird service API that can handle only one database at a time and does not report back, or you can create a complex backup service that can handle many databases simultaneously, on a regular basis (has a scheduler), uses a global resource registry for server, database and backup specification, uses a logging service, can do proximity-based load balancing to fellow backup services and will send information about its status and progress to some messaging pipe, and **either service would be a first-class well-behaving citizen in a Butler deployment**. + +Platform implementation +----------------------- + +Platform :doc:`specifications ` (a set of RFC documents) are blueprints for Platform implementation in various programming languages. The **reference implementation** is in the Python programming language, but within the Butler project, we would also like to provide implementations for C#, Java, Delphi, and Free Pascal. However, the Firebird Project has **currently** resources only for implementations in :ref:`Python `, :ref:`Java ` and :ref:`Free Pascal `. + +Because a platform specification does not define exact API or implementation details, the individual implementations may vary in their design, architecture, features and API provided for the service developers. There could be even multiple implementations in the same programming language that provide different features or architecture (for example, Python implementation for Python 2.7 and another for Python 3.6+ that takes advantage from async processing language features, or different async libraries like `trio`, `curio`, `twisted` or `asyncio`). + +.. note:: + + Applications and Butler Services created using **any** platform implementation will be able to bind and communicate with any Butler service, regardless of the platform on which it is implemented. However, individual platform implementations could provide additional integration options and features for applications and services that use the same platform implementation, beyond the options and features defined by the Butler Platform specification. + +| + +Firebird Butler Services +======================== + +A Butler Service is basically a piece of software that uses `ZeroMQ socket` and :doc:`Firebird the Butler Service Protocol ` for communication over this ZeroMQ channel. A service could use multiple ZeroMQ sockets for various purposes, but only one primary socket is required to support the Butler Service protocol. + +**Butler Services could do anything**, but a well designed service does only one task, or a small set of closely related tasks within single category. While respecting the rule of simplicity, services can be divided into several basic types: + +- `Measuring` services, that collect and pass on data. For example it may collect data from monitoring tables. +- `Processing` services, that take data on input, do something (on them) and have some data on output. This general category includes services that perform analytics, data transformation, brokers, bridges, routers, aggregators, load balancers etc. +- `Provider` services, that do things on request. For example perform a database backup. +- `Control` services, that manage other services. + + +Planned services +---------------- + +.. note:: + + The following overview contains only services that we currently consider to be the core of the Firebird Butler (product). They represent a road map for developing the first version within the :ref:`Saturnin` sub-project. + +*Measuring* services +^^^^^^^^^^^^^^^^^^^^ + +At first we want to take advantage of existing Firebird features (API, monitoring tables, trace service, user queries etc.) to provide data about transactions, connections, queries, security, configuration, resources, availability, operational information (logs, gstat output etc.). Consequently, we assume that additional user requirements for new information sources or formats will be met in collaboration with the Firebird engine developers. + +*Processing* services +^^^^^^^^^^^^^^^^^^^^^ + +We plan to create **at least** the following set of services in this category: + +- User-defined state machine analytics on measured data to trigger actions or emit signals +- Export of metrics to the Graphite_ open source monitoring product (primarily as metrics storage and a visualization solution) +- Import the connector for the python-diamond_ open source daemon that collects system metrics such as cpu, memory, network, i/o, load, disk etc. +- Notification service to send reports and alerts via e-mail and other means. +- Logging service, to collect log entries from other services. + +*Provider* services +^^^^^^^^^^^^^^^^^^^ +We plan to create **at least** the following set of services in this category: + +- Registry service for services and other resources, as a solution for central configuration needs. +- Scheduler service to run jobs on a regular basis +- Extensible storage service (it will provide at least file-based storage) +- Services for Firebird-related tasks like: backup & restore (gbak and nbackup), sweep and other tasks provided by gfix, cancellation of connections and transactions, user defined SQL commands and scripts +- Service to run user defined action -> external program or script + +*Control* services +^^^^^^^^^^^^^^^^^^ + +We plan to create **at least** the following set of services in this category: + +- General control service that uses Butler protocol specification to keep track of the state and configuration of registered running services, could emit signals and other information messages about it, and provide management service activities within the scope defined by the Butler protocol. +- A command-line tool to interact with this control service. + +| + +Where to go next +================ + +* The Firebird "Butler" Project :doc:`structure and organization ` +* The Firebird Butler :doc:`Specifications ` +* The `Firebird Project`_ main website + +| +| + +.. [1] Do you know that *InterBase* (the progenitor of the *Firebird RDBMS*) pioneered several technology concepts like *Multi-version Concurrency Control* (MVCC_) or BLOBs_? + + +.. _IBPhoenix: http://www.ibphoenix.com +.. _Firebird: http://www.firebirdsql.org +.. _Firebird Project: http://www.firebirdsql.org +.. _Zato: https://zato.io/ +.. _ZeroMQ: http://zeromq.org/ +.. _ZGuide: http://zguide.zeromq.org/ +.. _JeroMQ: https://github.com/zeromq/jeromq +.. _NetMQ: https://github.com/zeromq/netmq +.. _Graphite: https://graphiteapp.org/ +.. _python-diamond: https://github.com/python-diamond/Diamond +.. _MVCC: https://en.wikipedia.org/wiki/Multiversion_concurrency_control +.. _BLOBs: http://www.ibphoenix.com/resources/documents/history/doc_299 diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..3f6d050 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=.build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/organization.rst b/organization.rst new file mode 100644 index 0000000..5e8624f --- /dev/null +++ b/organization.rst @@ -0,0 +1,127 @@ +#################### +Project organization +#################### + + +Basic project structure +======================= + + +Firebird Butler is an extensive project, divided into several layers and pillars. + +The layers are: + +1. **Specifications and other documents** + + This is the shared foundation of the Butler project. This document collection (in which this text is included) contains a description of the project, its parts and how they fit in with each other, the specification of the developer platform, the used communication protocols, and the recommended practices for their implementation and use. It also includes the specification of selected services implemented within the project, and other related documentation. + + All these documents (provided under `CC-BY-SA-4.0` license) reside in the `Butler repository `_ on GitHub. They are also accessible in HTML and other formats at `readthedocs`. + + The main communication channel for discussion of specifications, implementation strategies, and other issues related to the whole project or its basics is the `firebird-butler forum `_ on googlegroups. + + .. tip:: + + There is also a low-traffic, read-only `annoucement list `_ for delivery of information about new releases and other important events related to the project. + +2. **Implementations of the Butler SDK** + + Different implementations of the development platform represent the individual pillars of the project. These pillars are typically formed around a particular programming language or development environment. Currently, due to limited resources, the project has only three pillars: + + 1. `saturnin-sdk`_ : a reference implementation in Python + 2. `ButlerJavaSDK`_ : implementation in Java + 3. :ref:`Butler SDK for Free Pascal ` : implementation in Free Pascal + + We hope the project's potential will attract other developers to help us deliver implementations also for Delphi, C# and other environments. + + Each SDK is a sub-project with its own repositories, communication channels, developers and documentation. + +3. **Implementations of Butler Services** + + Implementation of :doc:`Butler services ` is structured into stand-alone sub-projects because it is typically defined by the SDK used and the specific focus. Any such project can define its own standards and specifications beyond the basic :doc:`specifications for Butler Services `. The basic specifications then provide the necessary minimum level of interoperability between Services implemented by different sub-projects. + + Within the Firebird Butler project, only one sub-project of this type is currently being developed - a Firebird Butler implementation in Python called `Saturnin`_. Its aim is to provide a standard solution for management of Firebird deployments of any size, structure and complexity with an emphasis on large corporate installations. + + However, other such projects with different focus and features can be developed both within and outside the Firebird Butler project. + +4. **Distribution packages** + + Distribution bundles are the final product designed for common users. Like Linux distributions, they can include and combine various results from different Butler implementation projects to achieve different goals. + + Since the Firebird Butler project is only in its beginnings, no distributions are yet available. + +.. _saturnin-sdk: + +Saturnin SDK +============ + +The purpose of the *Saturnin SDK* sub-project is to provide basic tools for Python to create :doc:`Firebird Butler services ` while providing a reference implementation of :doc:`Firebird Butler specifications `. + +.. list-table:: + :widths: 30 70 + + * - Lead developer + - `Pavel Císař `_ + * - GitHub home repository + - `FirebirdSQL / saturnin-sdk `_ + * - Documentation and other information sources + - `readthedocs` + * - Main communication channel + - `saturnin-sdk forum `_ at googlegroups + +.. _ButlerJavaSDK: + +ButlerJavaSDK +============= + +The purpose of the *ButlerJava SDK* sub-project is to provide basic tools for Java to create :doc:`Firebird Butler services ` in accordance to :doc:`Firebird Butler specifications `. + +.. list-table:: + :widths: 30 70 + + * - Lead developer + - `Sergey Nikitin `_ + * - GitHub home repository + - `FirebirdSQL / ButlerJavaSDK `_ + * - Documentation and other information sources + - `readthedocs` + * - Main communication channel + - `butlerj-sdk forum `_ at googlegroups + +.. _butler-fpc-sdk: + +Butler SDK for Free Pascal +========================== + +The purpose of the *Butler SDK for Free Pascal* sub-project is to provide basic tools for Free Pascal and Lazarus to create :doc:`Firebird Butler services ` in accordance to :doc:`Firebird Butler specifications `. + +.. list-table:: + :widths: 30 70 + + * - Lead developer + - `Paul Reeves `_ + * - GitHub home repository + - `FirebirdSQL / butler-fpc-sdk `_ + * - Documentation and other information sources + - `readthedocs` + * - Main communication channel + - `butler-fpc-sdk forum `_ at googlegroups + +.. _saturnin: + +Saturnin +======== + +The purpose of the *Saturnin* sub-project is to provide Python-based standard solution, using the Saturnin SDK, for management of Firebird deployments of any size, structure and complexity with an emphasis on large corporate installations. The :doc:`main focus ` of the project is the creation of services and a platform for their deployment within an integrated solution. + +.. list-table:: + :widths: 30 70 + + * - Lead developer + - `Pavel Císař `_ + * - GitHub home repository + - `FirebirdSQL / saturnin `_ + * - Documentation and other information sources + - `readthedocs` + * - Main communication channel + - `firebird-saturnin forum `_ at googlegroups + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..373915e --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +sphinx-bootstrap-theme==0.6.5 diff --git a/rfc/1/C4.rst b/rfc/1/C4.rst new file mode 100644 index 0000000..d9716a8 --- /dev/null +++ b/rfc/1/C4.rst @@ -0,0 +1,159 @@ +############################################ +1/C4 - Collective Code Construction Contract +############################################ + +:domain: github.com/FirebirdSQL/Butler +:shortname: 1/C4 +:name: Collective Code Construction Contract +:status: draft +:editor: Pavel Císař + + +C4 provides a standard process for contributing, evaluating and discussing improvements on software projects. It defines specific technical requirements for projects, establishes different personas for projects with clear and distinct duties, and specifies a process for documenting and discussing issues including seeking consensus. + +This specification is derived from `C4 revision 3 `_ specification used by the ZeroMQ community. + +This is revision 1 of the C4 specification. + +License +======= + +Copyright (c) 2009-2016 Pieter Hintjens. +Copyright (c) 2016-2018 The ZeroMQ developers. +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. + +This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses. + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. note:: + + All ideas and change proposals SHOULD be presented and discussed first in the `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +1. Goals +======== + +C4 is meant to provide a reusable optimal collaboration model for open source software projects. It has these specific goals: + +#. To maximize the scale and diversity of the community around a project, by reducing the friction for new Contributors and creating a scaled participation model with strong positive feedbacks; +#. To relieve dependencies on key individuals by separating different skill sets so that there is a larger pool of competence in any required domain; +#. To allow the project to develop faster and more accurately, by increasing the diversity of the decision making process; +#. To support the natural life cycle of project versions from experimental through to stable, by allowing safe experimentation, rapid failure, and isolation of stable code; +#. To reduce the internal complexity of project repositories, thus making it easier for Contributors to participate and reducing the scope for error; +#. To enforce collective ownership of the project, which increases economic incentive to Contributors and reduces the risk of hijack by hostile entities. + +2. Design +========= + +2.1. Preliminaries +------------------ + +#. The project SHALL use the git distributed revision control system. +#. The project SHALL be hosted on github.com or equivalent, herein called the "Platform". +#. The project SHALL use the Platform issue tracker. +#. The project SHOULD have clearly documented guidelines for code style. +#. A "Contributor" is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem. +#. A "Maintainer" is a person who merges patches to the project. Maintainers does not need to be developers; their job is to enforce process. +#. A "Core Developer" is a person who is a Maintainer and an active Contributor at the same time. +#. A "Project Leader" is Core Developer who is responsible for resolving potential conflicts about technical or organizational issues towards a consensus, with the right to make a final decision on a particular problem if the consensus can not be reached. +#. Contributors SHALL NOT have commit access to the repository unless they are also Maintainers. +#. Maintainers SHALL have commit access to the repository. +#. Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract. + +2.2. Licensing and Ownership +---------------------------- + +#. The project SHALL use a Creative Commons license or an OSI Approved license, preferably a share-alike license such as the CC BY-SA 4.0, MPLv2, or a GPLv3 variant thereof (GPL, LGPL, AGPL). +#. All contributions to the project source code ("patches") SHALL use the same license as the project. +#. All patches are owned by their authors. There SHALL NOT be any copyright assignment process. +#. Each Contributor SHALL be responsible for identifying themselves in the project Contributor list. + +2.3. Patch Requirements +----------------------- + +#. Maintainers and Contributors MUST have a Platform account and SHOULD use their real names or a well-known alias. +#. A patch SHOULD be a minimal and accurate answer to exactly one identified and **agreed** problem. +#. A patch MUST adhere to the code style guidelines of the project if these are defined. +#. A patch MUST adhere to the "Evolution of Public Contracts" guidelines defined below. +#. A patch SHALL NOT include non-trivial code from other projects unless the Contributor is the original author of that code. +#. A patch MUST compile cleanly and pass project self-tests on at least the principal target platform. +#. A patch commit message MUST consist of a single short (less than 50 characters) line stating the problem ("Problem: ...") being solved, followed by a blank line and then the proposed solution ("Solution: ..."). +#. A "Correct Patch" is one that satisfies the above requirements. + +2.4. Development Process +------------------------ + +#. Change on the project SHALL be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems. +#. To request changes, a user SHOULD log an issue on the project Platform issue tracker. +#. The user or Contributor SHOULD write the issue by describing the problem they face or observe. +#. The user or Contributor SHOULD seek consensus on the accuracy of their observation, and the value of solving the problem. +#. Users SHALL NOT log feature requests, ideas, suggestions, or any solutions to problems that are not explicitly documented and provable. +#. Thus, the release history of the project SHALL be a list of meaningful issues logged and solved. +#. To work on an issue, a Contributor SHALL fork the project repository and then work on their forked repository. +#. The intended solution for non-trivial issues SHOULD be discussed first to avoid potential misdirections and collisions with others. +#. To submit a patch, a Contributor SHALL create a Platform pull request back to the project. +#. A Contributor SHALL NOT commit changes directly to the project. +#. If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue. +#. To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere. +#. To accept or reject a patch, a Maintainer SHALL use the Platform interface. +#. Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days), or if there is only one Maintainer. +#. Maintainers SHALL NOT make value judgments on correct patches. +#. Maintainers SHALL merge correct, undisputed patches from other Contributors rapidly. +#. Maintainers MAY merge incorrect patches from other Contributors with the goals of (a) ending fruitless discussions, (b) capturing toxic patches in the historical record, (c) engaging with the Contributor on improving their patch quality. +#. The user who created an issue SHOULD close the issue after checking the patch is successful. +#. Any Contributor who has value judgments on a patch SHOULD express these via their own patches. +#. Maintainers SHOULD close user issues that are left open without action for an uncomfortable period of time. + +2.5. Branches and Releases +-------------------------- + +#. The project SHALL have one branch ("master") that always holds the latest in-progress version and SHOULD always build. +#. The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches. +#. To make a stable release a Maintainer shall tag the repository. Stable releases SHALL always be released from the repository master. + +2.6. Evolution of Public Contracts +---------------------------------- + +#. All Public Contracts (APIs or protocols and their behaviour and side effects) SHALL be documented. +#. All Public Contracts SHOULD have space for extensibility and experimentation. +#. A patch that modifies a stable Public Contract SHOULD not break existing applications unless there is overriding consensus on the value of doing this. +#. A patch that introduces new features SHOULD do so using new names (a new contract). +#. New contracts SHOULD be marked as "draft" until they are stable and used by real users. +#. Old contracts SHOULD be deprecated in a systematic fashion by marking them as "deprecated" and replacing them with new contracts as needed. +#. When sufficient time has passed, old deprecated contracts SHOULD be removed. +#. Old names SHALL NOT be reused by new contracts. +#. A new contract marked as "draft" MUST NOT be changed to "stable" until all the following conditions are met: + #. Documentation has been written and is as comprehensive as that of comparable contracts. + #. Self-tests exercising the functionality are passing on the principal target platform. + #. No changes in the contract have happened for at least one public release. + #. No changes in the contract have happened for at least 6 months. + #. No veto from the Contributor(s) of the new contract and its implementation on the change of status. + +#. A new contract marked as "draft" SHOULD be changed to "stable" when the above conditions are met. +#. The "draft" to "stable" transition status for new contracts SHOULD be tracked using the Platform issue tracker. + +2.7. Project Administration +--------------------------- + +#. The project founders SHALL act as Administrators to manage the set of project Maintainers and Core Developers. +#. One of the Core Developers (or Maintainers if there are no Core Developers) MUST always be appointed as the Project Leader. +#. The Administrators SHALL ensure their own succession over time by promoting the most effective Maintainers or Core Developers. +#. A Contributor who makes correct patches, who clearly understands the project goals, and the process SHOULD be invited to become a Maintainer / Core Developer. +#. Administrators SHOULD remove Maintainers / Core Developers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately. +#. Administrators SHOULD block or ban "bad actors" who cause stress and pain to others in the project. This should be done after public discussion, with a chance for all parties to speak. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others. + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` + diff --git a/rfc/2/COSS.rst b/rfc/2/COSS.rst new file mode 100644 index 0000000..079e253 --- /dev/null +++ b/rfc/2/COSS.rst @@ -0,0 +1,224 @@ +################################################ +2/COSS - Consensus-Oriented Specification System +################################################ + +:domain: github.com/FirebirdSQL/Butler +:shortname: 2/COSS +:name: Consensus-Oriented Specification System +:status: draft +:editor: Pavel Císař + + +This document describes a consensus-oriented specification system (COSS) for building interoperable technical specifications. COSS is based on a lightweight editorial process that seeks to engage the widest possible range of interested parties and move rapidly to consensus through working code. + +This specification is derived from the `COSS `_ specification used by ZeroMQ project. + +This is revision 1 of the COSS specification. + +License +======= + +Copyright (c) 2008-16 the Editor and Contributors. +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. + +This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses. + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (i.e. by itself). + +.. note:: + + All ideas and change proposals SHOULD be presented and discussed first in the `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Goals +===== + +The primary goal of COSS is to facilitate the process of writing, proving, and improving new technical specifications. A "technical specification" defines a protocol, a process, an API, a use of language, a methodology, or any other aspect of a technical environment that can usefully be documented for the purposes of technical or social interoperability. + +COSS is intended to above all be economical and rapid, so that it is useful to small teams with little time to spend on more formal processes. + +Principles: + +- We aim for rough consensus and running code. +- Specifications are small pieces, made by small teams. +- Specifications should have a clearly responsible editor. +- The process should be visible, objective, and accessible to anyone. +- The process should clearly separate experiments from solutions. +- The process should allow deprecation of old specifications. + +Specifications should take minutes to explain, hours to design, days to write, weeks to prove, months to become mature, and years to replace. + +Specifications have no special status except that accorded by the community. + +Architecture +============ + +COSS is designed around fast, easy to use communications tools. Primarily, COSS uses a `git` repository for editing and publishing specifications texts. Additionally, it uses `Sphinx`_ (or other similar system) for text processing and a `web site` for publishing specifications texts in other formats than raw text. + +- The domain is the conservancy for a set of specifications in a certain area. +- Each domain is implemented as an Internet site with fixed URI (preferably an Internet domain), hosting a `git repository` and optionally other communications tools. +- All specifications are stored in repository under `/rfc` directory. +- Each specification is a set of pages, together with comments, attached files, and other resources. +- All texts pages are in reStructuredText markup. +- Specifications exist as multiple pages, one page per version of the specification (see `Branching and Merging`_, below), with assigned unique incremental number. +- Specification text is stored in `/rfc//.rst` file. Thus, we refer to a specification by specifying its number and short name. +- All related files should be stored in the same directory as the main text file. +- New versions of the same specification will have new numbers (i.e. will reside in different directories). The syntax for a specification reference is:: + + /rfc//.rst + + For example, this specification is `github.com/FirebirdSQL/Butler/rfc/2/COSS.rst`. The short form `2/COSS` may be used when referring to the specification from other specifications in the same domain. The RST markup for inserting a hyperlink from the specification in the same domain in this case is:: + + :doc:`/rfc/2/COSS` # specification full name as link text + :doc:`2/COSS ` # specification shortname as link text + +Every specification (including branches) carries a different number. Lower numbers indicate more mature specifications, higher numbers indicate more experimental specifications. + + +COSS Lifecycle +============== + +Every specification has an independent lifecycle that documents clearly its current status. + +A specification has six possible states that reflect its maturity and contractual weight: + +.. image:: /rfc/2/lifecycle.png + +Raw Specifications +------------------ + +All new specifications are raw specifications. Changes to raw specifications can be unilateral and arbitrary. Those seeking to implement a raw specification should ask for it to be made a draft specification. Raw specifications have no contractual weight. + +Draft Specifications +-------------------- + +When raw specifications can be demonstrated, they become draft specifications. Changes to draft specifications should be done in consultation with users. Draft specifications are contracts between the editors and implementers. + +Stable Specifications +--------------------- + +When draft specifications are used by third parties, they become stable specifications. Changes to stable specifications should be restricted to cosmetic ones, errata and clarifications. Stable specifications are contracts between editors, implementers, and end-users. + +Deprecated Specifications +------------------------- + +When stable specifications are replaced by newer draft specifications, they become deprecated specifications. Deprecated specifications should not be changed except to indicate their replacements, if any. Deprecated specifications are contracts between editors, implementers and end-users. + +Retired Specifications +---------------------- + +When deprecated specifications are no longer used in products, they become retired specifications. Retired specifications are part of the historical record. They should not be changed except to indicate their replacements, if any. Retired specifications have no contractual weight. + +Deleted Specifications +---------------------- + +Deleted specifications are those that have not reached maturity (stable) and were discarded. They should not be used and are only kept for their historical value. Only Raw and Draft specifications can be deleted. + +Editorial control +================= + +A specification MUST have a single responsible editor, the only person who SHALL change the status of the specification through the lifecycle stages. + +A specification MAY also have additional contributors who contribute changes to it. It is RECOMMENDED to use the C4 process to maximize the scale and diversity of contributions. + +The editor is responsible for accurately maintaining the state of specifications and for handling all comments on the specification. + +Branching and Merging +===================== + +Any member of the domain MAY branch a specification at any point. This is done by copying the existing text, and creating a new specification with the same name and content, but a new number. The ability to branch a specification is necessary in these circumstances: + +- To change the responsible editor for a specification, with or without the cooperation of the current responsible editor. +- To rejuvenate a specification that is stable but needs functional changes. This is the proper way to make a new version of a specification that is in stable or deprecated status. +- To resolve disputes between different technical opinions. + +The responsible editor of a branched specification is the person who makes the branch. + +Branches, including added contributions, are derived works and thus licensed under the same terms as the original specification. This means that contributors are guaranteed the right to merge changes made in branches back into their original specifications. + +Technically speaking, a branch is a different specification, even if it carries the same name. Branches have no special status except that accorded by the community. + +Conflict resolution +=================== + +COSS resolves natural conflicts between teams and vendors by allowing anyone to define a new specification. There is no editorial control process except that practised by the editor of a new specification. The administrators of a domain (moderators) may choose to interfere in editorial conflicts, and may suspend or ban individuals for behaviour they consider inappropriate. + +Conventions +=========== + +Where possible editors and contributors are encouraged to: + +- Refer to and build on existing work when possible, especially IETF specifications. +- Contribute to existing specifications rather than reinvent their own. +- Use collaborative branching and merging as a tool for experimentation. + +Appendix A. Color Coding +======================== + +It is RECOMMENDED to use color coding to indicate specification's status. Color coded specifications SHOULD use the following color scheme: + +- |raw| +- |draft| +- |stable| +- |deprecated| +- |retired| +- |deleted| + +Appendix B. Metainformation +=========================== + +It is RECOMMENDED that specification metadata is specified as a YAML header (where possible) or a separate YAML file. This will enable programmatic access to specification metadata. + +.. list-table:: + :widths: 20 20 20 40 + :header-rows: 1 + + * - Key + - Value + - Type + - Example + * - domain + - specification domain + - string + - rfc.unprotocols.org + * - shortname + - short name + - string + - 2/COSS + * - name + - full name + - string + - Consensus-Oriented Specification System + * - status + - status + - string + - draft + * - editor + - editor name/email + - string + - Yurii Rashkovskii yrashk@gmail.com + * - contributors + - contributors + - list + - Pieter Hintjens ph@imatix.com, André Rebentisch andre@openstandards.de, Alberto Barrionuevo abarrio@opentia.es, Chris Puttick chris.puttick@thehumanjourney.net + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. _Sphinx: http://www.sphinx-doc.org +.. |raw| image:: /rfc/2/raw.svg +.. |draft| image:: /rfc/2/draft.svg +.. |stable| image:: /rfc/2/stable.svg +.. |deprecated| image:: /rfc/2/deprecated.svg +.. |retired| image:: /rfc/2/retired.svg +.. |deleted| image:: /rfc/2/deleted.svg + diff --git a/rfc/2/deleted.svg b/rfc/2/deleted.svg new file mode 100644 index 0000000..fbbb704 --- /dev/null +++ b/rfc/2/deleted.svg @@ -0,0 +1 @@ +statusstatusdeleteddeleted \ No newline at end of file diff --git a/rfc/2/deprecated.svg b/rfc/2/deprecated.svg new file mode 100644 index 0000000..9009ecf --- /dev/null +++ b/rfc/2/deprecated.svg @@ -0,0 +1 @@ +statusdeprecated \ No newline at end of file diff --git a/rfc/2/draft.svg b/rfc/2/draft.svg new file mode 100644 index 0000000..52c7a6c --- /dev/null +++ b/rfc/2/draft.svg @@ -0,0 +1 @@ +statusdraft \ No newline at end of file diff --git a/rfc/2/lifecycle.png b/rfc/2/lifecycle.png new file mode 100644 index 0000000..9ee9380 Binary files /dev/null and b/rfc/2/lifecycle.png differ diff --git a/rfc/2/raw.svg b/rfc/2/raw.svg new file mode 100644 index 0000000..4c2eb79 --- /dev/null +++ b/rfc/2/raw.svg @@ -0,0 +1 @@ +statusraw \ No newline at end of file diff --git a/rfc/2/retired.svg b/rfc/2/retired.svg new file mode 100644 index 0000000..ce3e470 --- /dev/null +++ b/rfc/2/retired.svg @@ -0,0 +1 @@ +statusretired \ No newline at end of file diff --git a/rfc/2/stable.svg b/rfc/2/stable.svg new file mode 100644 index 0000000..1148cd1 --- /dev/null +++ b/rfc/2/stable.svg @@ -0,0 +1 @@ +statusstable \ No newline at end of file diff --git a/rfc/3/FBSD.rst b/rfc/3/FBSD.rst new file mode 100644 index 0000000..7a12a8c --- /dev/null +++ b/rfc/3/FBSD.rst @@ -0,0 +1,219 @@ +########################################### +3/FBSD - Firebird Butler Service Definition +########################################### + +:domain: github.com/FirebirdSQL/Butler +:shortname: 3/FBSD +:name: Firebird Butler Service Definition +:status: raw +:editor: Pavel Císař + +This document describes a specific category of software components capable of providing their services to clients working in the same or different contexts where the context may be a thread or a process. It defines common functionality and operational parameters to ensure interoperability and integration under defined working conditions. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. note:: + + All ideas and change proposals SHOULD be presented and discussed first in the `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +1. Goals +======== + +The purpose of this specification is to define software components capable of efficient asynchronous communication with other components through both tight and loose bindings in a diverse operating environments. + +The main objectives are: + +#. Architecture openness. +#. Maximum simplicity. +#. Reliability. +#. Isolation of individual components. +#. Ability to communicate as efficiently as possible within both a single operating environment and across different operating environments where these are process threads or processes running on the same computing system or network with different performance characteristics. +#. The ability to create a reliable, comprehensive, dynamically modifiable and expandable system composed of such components. + +2. Architecture +=============== + +Firebird Butler `Service` is any software unit that performs an activity required by the `Client`, and where communication between the Service and the Client is solely through the exchange of messages via ZeroMQ sockets. + +The `Service` MUST meet the following criteria: + +#. Service MUST bind to at least one ZeroMQ `ROUTER` socket, referred to as `Service Socket`. +#. Service MAY use additional ZeroMQ sockets for internal purposes or as part of its public API, that are not `Service Sockets`. All such additional ZeroMQ sockets that are part of the Service public API MUST be detectable using the API available through `Service Sockets`. +#. Services MUST assign an identity on `Service Socket`. If there are multiple Service Sockets, they MUST use the same identity. This socket identity SHALL be the same as `Unique Service Instance ID` defined by |FBSP|. +#. If Service uses multiple `Service Sockets`, all of them MUST provide the same functionality to the Clients. It means that from Client perspective there shall be no difference in service **abilities** available and **methods** how they are accessible between different `Service Sockets`. However, Service MAY have different **operational** characteristics when responsing to request coming from different Service Sockets. +#. All messages coming through `Service Socket` MUST be processed as |FBSP| protocol messages. +#. Service MUST correctly define its properties and APIs as a binding contract with Clients through |FBSP| protocol messages. +#. Service SHALL NOT accept Client request through any other channel than `Service Socket`. + +The `Client` is any software unit that meets the following criteria: + +#. Client SHALL connect to `Service Socket` using ZeroMQ `DEALER` or `ROUTER` socket, referred to as `Client Socket`. +#. All messages coming through `Client Socket` MUST be processed as |FBSP| protocol messages. +#. Client MUST correctly define its properties as a binding contract with Service through |FBSP| protocol messages. +#. Client SHALL NOT send request to the Service through any other channel than `Client Socket`. + +.. _svc-recommendation: + +2.1 Services +------------ + +The method of implementation of the Service is not specifically defined or limited, but the following recommendations should be taken into account: + +#. The Service SHOULD have exactly defined boundaries (API) and SHOULD use only ZeroMQ sockets to communicate across this boundary (i.e. use ZeroMQ as its only API). +#. The Service could bind `Service Sockets` using any ZeroMQ transport protocol on any address. However, Service implementations SHOULD allow configuration of these parameters whenever and as much possible. +#. The Service SHOULD handle `Client` requests asynchronously. +#. The functionality provided by the Service to `Clients` via both the |FBSP| protocol and other channels SHOULD be defined by an open standard. +#. The Service SHOULD provide some method of discovery for its access points and connection methods available to its `Clients`. This method SHOULD be defined by an open standard. +#. The Service SHOULD provide a logging information about its activities. It is RECOMMENDED to use standardized methods and protocols for this purpose. See |FBSP| for details and |FBLP| for examples. +#. The Service SHOULD provide information about its internal state. It is RECOMMENDED to use standardized methods and protocols for this purpose. See |FBSP| for details and |SSTP| for examples. +#. The Service that provide services to `Clients` running in different process or on another Network node SHOULD support remote configuration and remote control. It is RECOMMENDED to use standardized methods and protocols for this purpose. See |FBSP| for details, and |RSCFG| and |RSCTRL| for examples. + +.. important:: + + Any violation of these recommendations SHOULD be clearly specified in Service documentation. + +2.2. Clients +------------ + +The method of implementation of the Service Client is not specifically defined or limited, but the following recommendations should be taken into account: + +#. The Client SHOULD handle requests to the `Service` asynchronously. + +.. important:: + + Any violation of these recommendations SHOULD be clearly specified in Client documentation. + + +3. Operation of services +======================== + +3.1 Context of the Service and the Client +----------------------------------------- + +Both the `Service` and the `Client` can run in the same or different context, the context being the process `thread` or the separate `process`, or a separate process on another `network node`. + +When using different ZeroMQ protocols, the following combinations can be achieved: + +.. list-table:: Client and Service Link Scenarios + :widths: 5 40 40 15 + :header-rows: 1 + + * - Scenario + - Service Context + - Client Context + - ZeroMQ protocol + * - **1.** + - Thread `T` of Process `P` on node `N` + - Thread `T` of Process `P` on node `N` + - `inproc`_ [1]_ + * - **2.** + - Thread `T1` of Process `P` on node `N` + - Thread `T2` of Process `P` on node `N` + - `inproc`_ [2]_ + * - **3.** + - Thread `T` of Process `P1` on node `N` + - Thread `T` of Process `P2` on node `N` + - `ipc`_, `tcp`_ [3]_ + * - **4.** + - Thread `T` of Process `P` on node `N1` + - Thread `T` of Process `P` on node `N2` + - `tcp`_ + +.. [1] This scenario requires an `ioloop` supported and shared by both, the `Client` and the `Service`. It is NOT RECOMMENDED to mix this context scenario with others. +.. [2] `inproc` is the most efficient, but other protocols could be used as well, especially when the same Service Socket should be used in multiple contexts scenarios. +.. [3] `ipc` is the most effective option but may not be available on all platforms. In such a case, use of `tcp` through local loopback is the RECOMMENDED option. + +Service could work with Clients using multiple scenarios at once. However, the following recommendations should be taken into account: + +#. The Service SHOULD use the minimum necessary number of `Service Sockets`. +#. The Service SHOULD use the most efficient protocol for each used scenario. + +Taking into account the previous recommendations, it is advised to use one of the following recipes for combined scenarios: + +.. list-table:: Client and Service Combined Scenarios + :widths: 30 70 + :header-rows: 1 + + * - Supported scenarios + - Service Sockets + * - **3.** and **4.** + - Efficiency and Simplicity: One socket using `tcp`_ transport + * - **2.** and **3.** + - - Efficiency: Two sockets, one using `inproc`_ for Clients from context **2.**, and one using `ipc`_ transport for Clients from context **3.** + - Simplicity: One socket using `tcp`_ transport for Clients from all contexts. + * - **2.**, **3.** and **4.** + - - Efficiency: Two sockets, one using `tcp`_ for Clients from context **3.** and **4.**, and one using `inproc`_ transport for Clients from context **2.** + - Simplicity: One socket using `tcp`_ transport for Clients from all contexts. + * - **2.** and **4.** + - - Efficiency: Two sockets, one using `tcp`_ for Clients from context **4.**, and one using `inproc`_ transport for Clients from context **2.** + - Simplicity: One socket using `tcp`_ transport for Clients from all contexts. + +.. tip:: + + When implementing `Services`, it is RECOMMENDED to use a procedure that allows the same service code to be used in different contexts through adapters or containers. Most typically, the Service could be implemented as a `Class`, that accepts `Service Socket` specification (`protocol` and `address`, or already bound 0MQ socket instance) as a `constructor` parameter. + + Alternatively, it is possible to encapsulate the service into another service that would act as a `router` or `bridge` to Clients or Services in another contexts. + +3.2 Services that use other Services +------------------------------------ + +One of the main goals of this specification is to enable the creation of services that do not work in isolation according to the client / server schema, but function as integral components of a larger integrated entity. To achieve this goal, it is essential for services to use other available services themselves. + +When implementing Services that are also Clients of other services, the following recommendations should be taken into account: + +#. The Client connection to other Service SHOULD be handled asynchronously. +#. The Service SHOULD use the minimum necessary number of `Client Sockets`. This could be achieved by using a ROUTER socket for connecting to multiple, even different Services. +#. The Service SHOULD open the `Client Socket` to another service as soon as possible, preferably during its initialization, so that information about the availability and operating parameters of another service is known prior to processing the first request of the Service clients, where a Client request is a REQUEST message with a request code other than the code reserved for the |FBSP| protocol. +#. The client connection to another service SHOULD be kept open until the Service is terminated. +#. Information about client connections to other services SHOULD be part of the status information provided in accordance with :ref:`Recommendation 7, Section 2.1 `. +#. Configuration and management of client connections to other services SHOULD be part of the remote configuration and control provided in accordance with :ref:`Recommendation 8, Section 2.1 `. + +.. important:: + + For the successful creation of interconnected systems, due attention needs to be paid to the initialization and termination of Services, especially due to possible dependencies between Services. + + For systems built from components made up of separate processes or network nodes, due consideration should also be given to the mechanism of continuous monitoring and maintenance of the link between Services. + + It is RECOMMENDED to use standardized methods and protocols for these purposes. + + +3.3 Security +============ + +FBSD does not specify any authentication, encryption or access control mechanisms, and fully relies on security measures provided by ZeroMQ, or other means. + +4. Reference Implementations +============================ + +None at this time. In future, the :ref:`Saturnin` and :ref:`Saturnin-SDK ` will act as the prime reference implementation for FBSD. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSP| replace:: :doc:`4/FBSP` +.. |FBLP| replace:: :doc:`5/FBLP` +.. |SSTP| replace:: :doc:`6/SSTP` +.. |RSCFG| replace:: :doc:`7/RSCFG` +.. |RSCTRL| replace:: :doc:`8/RSCTRL` +.. _inproc: http://api.zeromq.org/4-2:zmq-inproc +.. _ipc: http://api.zeromq.org/3-2:zmq-ipc +.. _tcp: http://api.zeromq.org/3-2:zmq-tcp diff --git a/rfc/4/FBSP.rst b/rfc/4/FBSP.rst new file mode 100644 index 0000000..ffbbc83 --- /dev/null +++ b/rfc/4/FBSP.rst @@ -0,0 +1,985 @@ +######################################### +4/FBSP - Firebird Butler Service Protocol +######################################### + +:domain: github.com/FirebirdSQL/Butler +:shortname: 4/FBSP +:name: Firebird Butler Service Protocol +:status: raw +:editor: Pavel Císař + +The Firebird Butler Service Protocol (FBSP) defines formal rules for exchanging messages between Butler Service and its Client. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. important:: + + This specification is still incomplete (work in progress), hence the COSS change process is not yet fully applicable. All ideas and change proposals SHOULD be presented and discussed first in the `Firebird Butler forum `_. + +.. + Unfinished parts: + + .. todolist:: + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Related Specifications +====================== + +#. :doc:`/rfc/3/FBSD` +#. :doc:`/rfc/5/FBLP` +#. :doc:`/rfc/6/SSTP` +#. :doc:`/rfc/7/RSCFG` +#. :doc:`/rfc/8/RSCTRL` + +1. Goals +======== + +The purpose of this specification is to define formal rules for exchanging messages between Butler Service and its Client. Its goals are: + +#. Define the uniform structure of messages passed between the service and its client. +#. Define a uniform method and the minimum scope of integration of separate components (acting as services and clients) into an adaptable and reliable integrated system. +#. Standardize the format of the application interface between otherwise independent components. +#. Provide the resources necessary to implement efficient asynchronous communication between components with both tight and loose bindings in diverse operating environments. + + +2. Implementation +================= + +.. _connection: +.. _transport channel: + +2.1 Overall Behavior +-------------------- + +The specification requires the existence of a transport channel capable of asynchronously transmitting messages in both directions (referred to as `Transport Channel`), where individual messages are constituted by one or more uniquely separate data blocks (referred to as `Frames`). The `Transport Channel` must also conform to following rules: + +1. A message SHALL NOT be delivered more than once to any peer. +2. All messages between two immediate peers SHALL be delivered in order. + +.. tip:: + + Such transmissions are provided by ZeroMQ Message Transfer Protocol (ZMTP_) over ROUTER_ (and DEALER) sockets. + +Exchange of messages on the `Transport Channel` is implemented as a `Connection` between the `Service` and the `Client` where the connection has the following stages: + +1. The `Client` MUST initiate the connection by sending the HELLO_ message. +2. The `Service` MUST reply to the HELLO_ message by sending a WELCOME_ message to confirm the connection. If the Service can not receive the connection, it MUST send the ERROR_ message instead. +3. After confirming a successful `Connection`, the `Client` can start sending messages to which the `Service` responds by sending one or more messages of its own. +4. The `Client` or `Service` can terminate the `Connection` at any time by sending a CLOSE_ message, or by closing the `Transport Channel`. However, the peer initiating the connection termination SHOULD send the CLOSE_ message before it closes the Transport Channel to the other peer. + +.. important:: + + The conversation is always managed by the `Client`, that is, each message sent by the `Service` is always part of the response to some previous message sent by `Client`. + +.. _identity: +.. _Client Identity: +.. _Service Identity: + +2.2 Client and Service Identity +------------------------------- + +Both the `Client` and the `Service` must be uniquely identified. For this purpose, the specification introduces the concepts of `Client Identity` and `Service Identity`, collectively as `Identity`. + +1. The content of the `Identity` MAY be arbitrary. +2. There MUST be a canonical string `Identity` representation. +3. Both the `Client Identity` and the `Service Identity` MUST be unique in the same namespace. +4. Both the `Client` and the `Service` MUST use the `Identity` for all identification purposes. +5. If `Service` acts as a `Client` to another Service, then MUST use its own `Service Identity` as the `Client Identity` to the another Service. +6. It is RECOMMENDED that both the `Client` and the `Service` use the `Identity` for routing purposes. +7. It is RECOMMENDED to use UUID_ as `Identity`. + +.. tip:: + + When implementing FBSP using ZeroMQ sockets as a `Transport Channel`_, it is RECOMMENDED that the `Client` or `Service` assign their `Identity` as the identity of all ZeroMQ sockets used for FBSP protocol messaging. + +2.3 The Connection and the Transport Channel +-------------------------------------------- + +2.3.1 Using one Channel for multiple Connections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A single `Transport channel`_ MAY be used for message transmission for several concurrently active `Connections`. This specification does not define how the message routing for individual connections should be done, neither the necessary encapsulation of the FBSP protocol messages into the messages transmitted by the multi-transport channel. However, the possible implementation of the multi-transport channel MUST be completely transparent from the point of view of the FBSP. + +2.3.2 Bound and unbound Connections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This specification assumes that message transfer provided by `Transport Channel`_ is implemented via `Transport Connection` established between the Client and the Service. In such a case, the FBSP Connection_ MAY be bound or not to the `Transport Connection`. This means that: + +a) A bound `Connection` SHALL be terminated automatically when the `Transport Connection` functionality is interrupted. An unbound `Connection` assumes a mechanism exists for restoring an interrupted `Transport Connection`, and SHALL be terminated only if this mechanism fails. +b) For unbound `Connection` the `Transport Connection` does not need to be closed together with closing `Connection`, and MAY be reused to carry another subsequent `Connection` between the same `Client` and `Service`. For bound `Connection` the `Transport Connection` SHOULD be closed together with closing `Connection`. + +The method of agreement between the `Client` and the `Service` to use the bound or unbound `Connection` mechanism is not defined by this specification and MUST be provided by other means. If such other means are not used, the `Connection` MUST be **bound** to the `Transport Connection`. + + +2.4 FBSP Messages +----------------- + +The traffic between `Client` and `Service` consists of `Messages` in a unified format sent in both directions via a `Transport Channel`_. + +FBSP is designed to carry arbitrary `Service API` in unified message format. This is achieved by dividing the contents of the messages into a structural part (`Control Frame`) and a data (`Data Frames`). In addition to the basic structural information, the `Control Frame` also includes a space for the transmission of control data for the `Service API`. The API's main point is the `Request Code`_ that uniquely identifies the required functionality (API call). FBSP defines (and reserves) some `Request Codes`_ for itself, while unused ones are reserved for use by `Service`. With few exceptions, all `Data Frames` are considered as part of the `Service API`, and are not regulated by this specification. + +2.4.1 Formal message grammar +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _control-frame: +.. _data-frame: +.. _signature: +.. _control-byte: +.. _flags: +.. _type-data: +.. _token: + +The following ABNF grammar defines the message format used by FBSP protocol:: + + fbsp = *message + + ; The message consists of a control frame, and zero or more data frames + message = control-frame *data-frame + + ; The control frame consists of a signature, control byte, flags, message-type data, and message token + control-frame = signature control-byte flags type-data token + + ; The protocol signature is a FourCC + signature = "FBSP" ; %x46 %x42 %x53 %x50 + + ; The control byte encodes a message type, and protocol version. Both are decimal numbers. + ; msg-type on upper (leftmost) 5 bits, version on lower (rightmost) 3 bits + control-byte = 1OCTET + + ; Flags consists of a single octet containing various control flags as individual bits. + ; Bit 0 is the least significant bit (rightmost bit) + flags = 1OCTET + + ; Message-type specific data are two bytes + type-data = 2OCTET + + ; Message token is 8 bytes + token = 8OCTET + + ; A data frame consists from zero or more octets + data-frame = *OCTETS + +2.4.2 Message token +^^^^^^^^^^^^^^^^^^^ + +The FBSP allows asynchronous communication between the `Client` and the `Service`, and also allows the `Service` to send several messages in response to one message sent by the `Client`. `Message Token` is a client-specified data block that is sent back to the `Client` by a `Service` without change, in each message that is a logical response to that message. + +Processing of the token is governed by the following rules: + +1. The content of the `Message Token` MAY be arbitrary. +2. The content of the `Message Token` SHALL be specified by `Client` only. +3. The `Message Token` MUST be returned without change in any message sent by the `Service`, which is a logical response to the original message sent by the `Client` containing that token. +4. Messages sent by a `Service` that can not be uniquely identified as a logical response to a previous message sent by a `Client` (such as unexpected general ERROR_, CLOSE_, or NOOP_ sent to check the client's availability) MUST contain the `Message Token` passed by the `Client` in the HELLO_ message. + +.. important:: + + This specification does not define in any way how the `Client` should use the `Message Token`, nor does it prescribe that it should be used at all. However, the `Message Token` SHOULD be used by the `Client` whenever there is a need to assign messages sent by the `Service` to the original request source (for example for internal routing purposes or reliable implementation of parallel `Client` requests). + +.. _message-type: + +2.4.3 Message types +^^^^^^^^^^^^^^^^^^^ + +The message type is an integer in the range of 1..31 stored in 5 upper (leftmost) bits of the control-byte_. This protocol revision defines the next message types:: + + unused = 0 ; not a valid message type + HELLO = 1 ; initial message from client + WELCOME = 2 ; initial message from service + NOOP = 3 ; no operation, used for keep-alive & ping purposes + REQUEST = 4 ; client request + REPLY = 5 ; service response to client request + DATA = 6 ; separate data sent by either client or service + CANCEL = 7 ; cancel request + STATE = 8 ; operating state information + CLOSE = 9 ; sent by peer that is going to close the connection + reserved = 10..30 ; reserved for future use + ERROR = 31 ; error reported by service + +The `Client` SHALL send only messages of following types:: + + HELLO : must be the first message in conversation + NOOP : presence check + REQUEST : request to service + CANCEL : cancel previous request + DATA : data package sent to service + CLOSE : client is about to close the connection + +The `Service` SHALL send only messages of following types:: + + ERROR : error is always an error + WELCOME : must be the first message in conversation + NOOP : presence check + REPLY : reply to REQUEST message + DATA : data package sent to client + STATE : operating state information + CLOSE : service is about to close the connection + +HELLO +""""" + +The `HELLO` message is a `Client` request to open a Connection_ to the `Service`. The message includes basic information about the `Client` and Connection_ parameters required by the `Client`. + +1. This message MUST be the first message sent by the `Client`. +2. The `Service` MUST reply to this message with WELCOME_ or ERROR_ message. +3. The first data-frame_ of this message MUST contain the `Client Identity`_ (see `Data frames - HELLO` for details). +4. If the `Service` records an open Connection_ for a `Client` with the same `Client Identity`_, it MUST respond with ERROR_ message, and refuse the connection. +5. The content of type-data_ field in this message is not significant. **[RAW NOTE: Should we use it for something? HELLO protobuf format version? bitmap of requested common connection parameters?]** + +.. seealso:: + + `Data frames - HELLO` + +WELCOME +""""""" + +The WELCOME message is the response of the `Service` to the HELLO_ message sent by the `Client`, which confirms the successful creation of the required Connection_ and announces basic parameters of the `Service` and the Connection_. + +1. The first data-frame_ of this message MUST contain the `Service Identity`_ (see `Data frames - WELCOME` for details). +2. The content of type-data_ field in this message is not significant. **[RAW NOTE: Should we use it for something? WELCOME protobuf format version? bitmap of available common service abilities?]** + +.. seealso:: + + `Data frames - WELCOME` + +NOOP +"""" + +The NOOP message means no operation. It's intended for *keep alive* purposes and *peer availability checks*. + +1. The receiving peer SHALL NOT respond to this message. +2. The sole exception to rule 1. is the case when ACK-REQUEST_ flag is set in received NOOP message. In such a case the receiving peer MUST respond according to rules for ACK-REQUEST_ flag handling. +3. The content of type-data_ field in this message is not significant. However, because it’s returned by receiver without changes (when ACK-REQUEST flag is set), it MAY be used by sender for any purpose. +4. This message SHALL NOT have any data-frame_. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +REQUEST +""""""" + +The REQUEST message is a `Client` request to the `Service`. + +1. The type-data_ field of the control-frame_ MUST contain a `Request Code`_. +2. The message MAY contain one or more data-frame_ that MUST conform to the API defined for particular `Request Code`_. +3. The `Service` MUST respond to this message by sending REPLY_ or ERROR_ message with the same `Request Code`_ in type-data_ field. +4. The `Service` MAY send additional subsequent messages in response to the same REQUEST message. +5. The type and number of messages in reply to particular request, as well as method for indicating the end of the message stream to the `Client` SHALL be defined by the API for particular `Request Code`_. +6. When ACK-REQUEST_ flag is set in received REQUEST message, the `Service` MUST respond according to rules for ACK-REQUEST_ flag handling. This ACK response MUST be immediate, before further processing of the request. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +REPLY +""""" + +The REPLY message is a `Service` reply to the REQUEST_ message previously sent by `Client`. + +1. The type-data_ field of the control-frame_ MUST contain the `Request Code`_ from Client REQUEST_ message. +2. The message MAY contain one or more data-frame_ that MUST conform to the API defined for particular `Request Code`_. +3. The `Service` SHOULD NOT send more than one REPLY message to any single REQUEST message received. If reply requires more than single message, the REPLY message SHALL be the first message sent and subsequent messages SHOULD be of type DATA_ or STATE_. +4. The `Client` SHALL NOT respond to this message. +5. The sole exception to rule 4. is the case when ACK-REQUEST_ flag is set in received REPLY message. In such a case the `Client` MUST respond according to rules for ACK-REQUEST_ flag handling. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +DATA +"""" + +The DATA message is intended for delivery of arbitrary data between connected peers. + +1. The type-data_ field of the control-frame_ MAY have arbitrary content, and is fully available for the `Service` API. +2. The message SHOULD contain one or more data-frame_ that MUST conform to the API defined for particular `Request Code`_. +3. The FBSP does not provide any means to pair DATA messages sent by `Client` to the request they are related to. If `Service` API requires such assignment, it MUST be handled by API itself via content of transmitted data-frame_ parts of the message, or by type-data_ field of the control-frame_. +4. The receiver SHALL NOT respond to this message, with sole exceptions defined by rules 5. and 6. +5. When ACK-REQUEST_ flag is set in received DATA message, receiver MUST respond according to rules for ACK-REQUEST_ flag handling. +6. The `Service` MAY reply to received DATA message with ERROR_ message. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +CANCEL +"""""" + +The CANCEL message represents a request for a `Service` to stop processing the previous request(s) from the `Client`. + +1. The type-data_ field of the control-frame_ MUST contain the `Request Code`_ from Client REQUEST_ message to be canceled. +2. The message MAY contain one or more data-frame_ that MUST conform to the API defined for cancellation of particular `Request Code`_. +3. The `Service` MUST reply to this message with STATE_ or ERROR_ message. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +STATE +""""" + +The STATE message is sent by `Service` to report its operating state to the `Client`. + +1. The `Service` SHALL NOT send the STATE message on its own discretion, but only in relation to REQUEST_ message previously sent by `Client`. +2. The type-data_ field of the control-frame_ MUST contain the `Request Code`_ from Client REQUEST_ message this STATE message relates to. +3. The `Client` SHALL NOT respond to this message. +4. The sole exception to rule 3. is the case when ACK-REQUEST_ flag is set in received STATE message. In such a case the `Client` MUST respond according to rules for ACK-REQUEST_ flag handling. + +.. seealso:: + + `Flags - ACK-REQUEST `_ + +CLOSE +""""" + +The CLOSE message notifies the receiver that sender is going to close the Connection_. + +1. The receiver SHALL NOT respond to this message. +2. The receiver SHALL NOT use the Connection_ to send further messages to the sender. +3. For bound connections, the receiver SHALL close its end of the `Transport Channel`_ immediately. + + +ERROR +""""" + +The ERROR message notifies the `Client` about error condition detected by `Service`. + +1. The type-data_ field of the control-frame_ MUST contain the `Error Code`_. +2. The message MAY contain one or more data-frame_ that MUST conform to the API defined for reporting `Service` errors. Those data-frame_ parts MAY be ignored by `Client`. +3. The `Client` SHALL NOT respond to this message. + +.. seealso:: + + `Error codes`_ + +2.4.4 Flags +^^^^^^^^^^^ + +Flags are encoded as individual bits in flags_ field of the control-frame_. + +.. list-table:: Flags + :widths: 20 10 70 + :header-rows: 1 + + * - Name + - Bit + - Mask + * - **ACK-REQUEST** + - 0 + - 1 + * - **ACK-REPLY** + - 1 + - 2 + * - **MORE** + - 3 + - 4 + +ACK-REQUEST +""""""""""" + +The ACK-REQUEST flag is intended for verification and synchronization purposes. + +1. Any received control-frame_ of message-type_ NOOP_, REQUEST_, REPLY_, DATA_, STATE_ or CANCEL_ that have ACK-REQUEST flag set SHALL be sent back to the sender as confirmation of accepted message, unless the receiver is a `Service` and an error condition occurs. In such a case the ERROR_ message SHALL be sent by `Service` instead confirmation message. +2. Returned confirmatory message SHALL consists only from the received control-frame_ with ACK-REQUEST flag cleared, and with ACK-REPLY_ flag set (ie the control-frame_ MUST be otherwise unchanged). +3. The ACK-REQUEST flag SHALL be ignored for all message-type_ values not listed in rule 1. + +Rules for ACK-REQUEST received by `Service`: + +1. NOOP_ message SHALL be acknowledged without any delay. +2. REQUEST_ and CANCEL_ messages SHALL be acknowledged at the time the `Service` has positively decided to accept the client's request and before commencing the fulfillment of the client's request. +3. DATA_ message SHALL be acknowledged without any delay, unless a previous agreement between the `Client` and the `Service` exists to handle it differently (for example to send it when DATA message is actually processed and Service is able to accept another DATA message). + +Rules for ACK-REQUEST received by `Client`: + +1. NOOP_ and STATE_ message SHALL be acknowledged without any delay. +2. REPLY_ and DATA_ messages SHALL be acknowledged without any delay, unless a previous agreement between the `Client` and the `Service` exists to handle it differently (for example when `Client` is prepared to accept subsequent DATA or other messages from Service). + +ACK-REPLY +""""""""" + +The ACK-REPLY flag indicates that message is a confirmation of the message previously sent by receiver. + +1. The ACK-REPLY flag SHALL NOT be set for any message that is not a confirmation of previous message received with ACK-REQUEST_ flag set. +2. The message with ACK-REPLY flag set MUST conform to the rules defined for ACK-REQUEST_ flag handling. + +MORE +"""" + +The MORE flag is intended to signal the end of the logical message stream to the receiver. + +1. The MORE flag SHALL be set for all messages that are a part of logical message stream, and are not the terminal message of this stream. If the message stream is a response to `Client` request, the MORE flag SHALL be set in the REPLY_ message as well. +2. The MORE flag SHALL be cleared for all messages that are not part of the logical message stream, or are the terminal message of such stream. +3. The receiver SHALL ignore the MORE flag for all messages of message-type_ HELLO_, WELCOME_, NOOP_, REQUEST_, CANCEL_, CLOSE_ and ERROR_. + +2.4.5 Protocol versioning +^^^^^^^^^^^^^^^^^^^^^^^^^ + +General rules +""""""""""""" + +All revisions of this specification SHALL conform to following rules: + +1. All revisions SHALL preserve next parts of this revision: + + a) reqirements defined for `Transport Channel`_ + b) the existence of control-frame_ + c) the position, content and meaning of first five bytes of control-frame_, ie. the signature_ and the control-byte_ + d) the existence of message token_ + +2. All revisions SHALL preserve next parts of all previous revisions: + + a) defined :ref:`Message types ` + b) defined Flags_ + c) defined `Request Codes`_ + d) defined `Error Codes`_ + +Version negotiation +""""""""""""""""""" + +1. Both the `Client` and the `Service` SHALL use the same protocol version for all messages transmitted as part of a single Connection_. +2. The protocol version used for the Connection_ is defined by the `Client` in his HELLO_ message sent to the `Service`. +3. The `Service` SHALL use the same protocol version as the `Client`. +4. If `Service` cannot handle Connection_ in protocol version used by the `Client`, it SHOULD respond with appropriate ERROR_ message in format defined by this revision. The `Service` MAY respond to this condition by closing the `Transport Connection` associated with the Connection_ request. +5. The `Client` using different revision of this protocol than revision 1 SHOULD be able to handle ERROR_ message in format defined by this revision that would be send as response to his HELLO_ message. +6. The `Client` SHALL eventually interpret the closing of the `Transport Channel`_ to the `Service` without response to his HELLO_ message as rejection of his request to create the Connection_. + +2.5 Handling of client requests +------------------------------- + +The `Client` SHALL send its requests to the `Service` as REQUEST_ messages with `Request Code`_ indicating the required functionality (an API call). + +The handling of Client request has following general rules: + +1. The `Service` MUST always respond to the REQUEST_ message in one from following formats: + + a. Send the ERROR_ message describing the error status detected by the `Service` that prevents successful completion of the request. + b. Send the REPLY_ message as an indication of successful completion of the request, or as indication that `Service` started to fulfill the request. The actual meaning of this reply is defined by `Service API`. +2. An ERROR_ message sent to the `Client` SHALL always end the processing of the request. +3. The fulfillment of particular request MAY require multiple messages to be sent by `Service`. In such a case, service MUST send the REPLY_ message first, before any additional message would be sent. +4. The subsequent messages after REPLY_ message SHALL be only of message-type_ DATA_, STATE_ or ERROR_. +5. The `Service API` for particular `Request Code`_ that requires multiple messages to be send by `Service` SHALL use one from the following methods to indicate the end of request processing to the `Client`: + + a. Using MORE_ flag in REPLY_, DATA_ and STATE_ messages sent to the `Client`. It is RECOMMENDED to use it as preferred method for organization of the message stream. + b. Using STATE_ message with information that indicates the end of request processing. + c. Continuous processing terminated on `Client` request by CANCEL_ message or until Connection_ is not closed. + +.. _Request codes: +.. _Request Code: + +2.6 Request codes +----------------- + +The `Request Code` uniquely identifies the `Service` functionality (an API call). This specification define following rules for request codes: + +1. A `Request Code` SHALL be two-byte unsigned integer value (0 to 65,535) passed in type-data_ field in network byte order. +2. Values in range 0..999 SHALL be reserved for FBSP (including all future FBSP revisions). +3. Values in range 1000..65535 SHALL be reserved for free use in `Service API`. +4. Any single value from the range defined by rule 3. SHALL NOT be reserved for any single `Service API`, ie. any API MAY use the same value as another API. This effectively means that the `Service` must properly announce its API to the `Client` and therefore the meaning of the specific values before they could be used in REQUEST_ messages. +5. The `Service` MUST process all `Request Codes` in accordance with the FBSP revision that the Service uses to communicate with a specific `Client`. + +2.6.1 FBSP Request Codes +^^^^^^^^^^^^^^^^^^^^^^^^ + +This specification defines following Request Codes: + + +.. list-table:: *FBSP Request Codes* + :widths: 10 5 15 70 + :header-rows: 1 + + * - Name + - Value + - Implementation + - Action + * - ALL_REQESTS_ + - 0 + - REQUIRED + - For use with CANCEL_ message to cancel all active `Client` requests + * - SVC_ABILITIES_ + - 1 + - REQUIRED + - SHALL return `Service abilities` + * - SVC_CONFIG_ + - 2 + - REQUIRED + - SHALL return current `Service configuration` + * - SVC_STATE_ + - 3 + - REQUIRED + - SHALL return current `Service operational state` + * - SVC_SET_CONFIG_ + - 4 + - OPTIONAL + - SHALL change current `Service configuration` + * - SVC_SET_STATE_ + - 5 + - OPTIONAL + - SHALL change current `Service operational state` + * - SVC_CONTROL_ + - 6 + - OPTIONAL + - SHALL perform `Service Control Action` + * - + - 7..19 + - + - Reserved + * - CON_REPEAT_ + - 20 + - OPTIONAL + - SHALL repeat last message(s) sent + * - CON_CONFIG_ + - 21 + - REQUIRED + - SHALL return current `Connection configuration` + * - CON_STATE_ + - 22 + - REQUIRED + - SHALL return current `Connection operational state` + * - CON_SET_CONFIG_ + - 23 + - OPTIONAL + - SHALL change current `Connection configuration` + * - CON_SET_STATE_ + - 24 + - OPTIONAL + - SHALL change current `Connection operational state` + * - CON_CONTROL_ + - 25 + - OPTIONAL + - SHALL perform `Connection Control Action` + * - + - 26..999 + - + - Reserved + +ALL_REQESTS +""""""""""" + +1. ALL_REQESTS is a valid code only for CANCEL_ messages. `Service` SHALL reply with ERROR_ message when this code is used in REQUEST_ message. +2. The `Service` SHALL terminate all currently active requests of the `Client`, and send the REPLY_ message to the `Client` when request is successfully finished. The data-frame_ in REPLY_ message MUST conform to the protocol-buffer_ format defined for CANCEL_ message. +3. If the `Service` cannot terminate **all** active requests, it SHALL respond with ERROR_ message. +4. If the `Service` cannot terminate **some** active requests, it SHALL NOT be an error condition. All partial failures SHALL be noted in the data-frame_ of the REPLY_ message. +5. If there are no active `Client` requests, it SHALL NOT be an error condition. + +SVC_ABILITIES +""""""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe its abilities in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +SVC_CONFIG +"""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe its current configuration in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +SVC_STATE +""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe its current operational state in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +SVC_SET_CONFIG +"""""""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe its abilities in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +SVC_SET_STATE +""""""""""""" + +1. The `Service` SHALL change its operational state to the one described in data-frame_ passed in the received REQUEST_ message. +2. The `Service` SHALL reply with single REPLY_ message that indicates the result in the data-frame_. +3. Both REQUEST_ and REPLY_ data-frame_ MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +SVC_CONTROL +""""""""""" + +1. The `Service` SHALL perform the `Service Control Action` described in data-frame_ passed in the received REQUEST_ message. +2. The `Service` SHALL reply with single REPLY_ message that indicates the result in the data-frame_. +3. Both REQUEST_ and REPLY_ data-frame_ MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +CON_REPEAT +"""""""""" + +1. The `Client` MUST describe the requested messages in data-frame_ passed in the REQUEST_ message, that MUST conform to the protocol-buffer_ format defined for this `Request Code`.. +2. The `Service` SHALL reply with single REPLY_ message that indicates that request was accepted and Service will start sending requested messages. +3. The `Service` SHALL send messages requested by `Client` as DATA_ messages related to original REQUEST_ with one or more data-frame_ parts that hold the requested message (the control-frame_ of the requested message is thus the first data-frame_ of DATA_ message sent to the `Client`). +4. The requested messages SHALL be resent in original order. +5. The `Service` SHALL use MORE flag to organize the DATA_ message stream for the `Client`. + +CON_CONFIG +"""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe the current configuration of active Connection_ in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +CON_STATE +""""""""" + +The `Service` SHALL reply with single REPLY_ message that describe the actual operational state of active Connection_ in the data-frame_ that MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +CON_SET_CONFIG +"""""""""""""" + +1. The `Service` SHALL change the configuration of the Connection_ to the one described in data-frame_ passed in the received REQUEST_ message. +2. The `Service` SHALL reply with single REPLY_ message that indicates the result in the data-frame_. +3. Both REQUEST_ and REPLY_ data-frame_ MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +CON_SET_STATE +""""""""""""" + +1. The `Service` SHALL change the operational state of the Connection_ to the one described in data-frame_ passed in the received REQUEST_ message. +2. The `Service` SHALL reply with single REPLY_ message that indicates the result in the data-frame_. +3. Both REQUEST_ and REPLY_ data-frame_ MUST conform to the protocol-buffer_ format defined for this `Request Code`. + +CON_CONTROL +""""""""""" + +1. The `Service` SHALL perform the `Connection Control Action` described in data-frame_ passed in the received REQUEST_ message. +2. The `Service` SHALL reply with single REPLY_ message that indicates the result in the data-frame_. +3. Both REQUEST_ and REPLY_ data-frame_ MUST conform to the protocol-buffer_ format defined for this `Request Code`. + + +.. _protocol-buffer: + +2.7 Data frames +--------------- + +Where control-frame_ contains semantic specification of the message, individual data-frame_ parts of the message carry data associated with given API call or response. + +Number, content and structure of individual `data-frames` SHALL be defined by API specification for particular message-type_ and/or `Request Code`_. + +2.7.1 General rules +^^^^^^^^^^^^^^^^^^^ + +All API and other specifications that define data-frame_ contents SHALL conform to following rules: + +1. The message SHALL have minimal necessary number of `data-frames`. +2. The total size of all `data-frames` in single message SHOULD NOT exceed 50MB. +3. Any peer MAY set a Connection_ limit on total size (in bytes) for any single message transmitted that SHALL NOT be smaller than 1MB. Such limit SHALL be announced to other peer in HELLO and WELCOME message. Such limit MAY be negotiable between peers after Connection_ is successfully established. +4. All API and other specifications that define rules for data-frame_ contents SHOULD use serialization to store structured data into data-frame_. The RECOMMENDED serialization methods are `Protocol Buffers`_ (preferred) or `Flat Buffers`_ (in case the direct access to parts of serialized data is required). It is NOT RECOMMENDED to use any verbose serialization format such as JSON or XML. The whole Service API SHOULD use only one serialization method. Serialization method MAY be negotiable between peers. + + +2.7.2 FBSP Data Frames for message types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. todo:: + :class: todo + + Define protocol buffers for HELLO, WELCOME and CANCEL messages. + +HELLO data +"""""""""" + +WELCOME data +"""""""""""" + +CANCEL data +""""""""""" + +2.7.3 FBSP Data Frames for Request Codes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SVC_ABILITIES data +"""""""""""""""""" + +.. todo:: + :class: todo + + Define protocol buffers for SVC_ABILITIES. + +SVC_CONFIG data +""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/7/RSCFG` specification. + +SVC_STATE data +"""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/6/SSTP` specification. + +SVC_SET_CONFIG data +""""""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/7/RSCFG` specification. + +SVC_SET_STATE data +"""""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/6/SSTP` specification. + +SVC_CONTROL data +"""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/8/RSCTRL` specification. + +CON_REPEAT data +""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/8/RSCTRL` specification. + +CON_CONFIG data +""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/7/RSCFG` specification. + +CON_STATE data +"""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/6/SSTP` specification. + +CON_SET_CONFIG data +""""""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/7/RSCFG` specification. + +CON_SET_STATE data +"""""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/6/SSTP` specification. + +CON_CONTROL data +"""""""""""""""" + +The data-frame_ SHALL conform to :doc:`/rfc/8/RSCTRL` specification. + +.. _error codes: +.. _error code: + +2.8 Error codes +--------------- + +Errors are transmitted in type-data_ field of the ERROR_ message. + +1. The `Error Code` is a 11-bit unsigned integer number encoded in upper (leftmost) bits of the type-data_ field of ERROR_ message. The `Error Code` is thus a value in range 0..2047. +2. The lower (rightmost) 5 bits of type-data_ field encode the message-type_ this particular error relates to (the bitmask is 31). The "zero" value represents general, out-of-band error reported by `Service`. +3. The `Error Code` range (0..2047) is divided into next categories:: + + 1..999 : Reserved by FBSP for general errors indicating that particular request cannot be satisfied ("soft" errors) + 1000..1999 : Reserved for use by Service API + 2000..2047 : Reserved by FBSP for general errors indicating that connection would or should be terminated (severe errors) + +2.8.1 Error codes defined by FBSP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. todo:: + :class: todo + + Add list of error codes defined by FBSP. + +3. Reference Implementations +============================ + +None at this time. In future, the :ref:`Saturnin-SDK ` will act as the prime reference implementation for FBSP. + + +| +| + +Appendix A. Transmission patterns +================================= + +Keep alive +---------- + +.. aafig:: + + +---------+ +----------+ + | Sender | | Receiver | + +----+----+ +-----+----+ + | | + X "NOOP" | + X------------------------>* + X | + + +Peer availability check +----------------------- + +.. aafig:: + + +---------+ +----------+ + | Sender | | Receiver | + +----+----+ +-----+----+ + | | + X "NOOP/ACK-REQEST" | + X------------------------>X + | X + | X + | "NOOP/ACK-REPLY" X + X<------------------------X + X | + +Failed Client request +--------------------- + +.. aafig:: + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | X + | "ERROR" X + X<------------------------X + X | + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | "STREAM TRAFFIC" X + *<----------------------->X + | X + | "ERROR" X + X<------------------------X + X | + +Simple Client request +--------------------- + +.. aafig:: + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | X + | REPLY X + X<------------------------X + X | + +Client request with message stream +---------------------------------- + +Using MORE_ flag: + +.. aafig:: + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | REPLY (MORE) X + *<------------------------X + | X + | "DATA/STATE (MORE)" X + *<------------------------X + | X + | "DATA/STATE (MORE)" X + *<------------------------X + | X + | "DATA/STATE (MORE)" X + *<------------------------X + | X + | "DATA/STATE" X + X<------------------------X + X | + +Using STATE_ message: + +.. aafig:: + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | REPLY X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | STATE [end] X + X<------------------------X + X | + +Using CANCEL_ message: + +.. aafig:: + + +---------+ +----------+ + | Client | | Service | + +----+----+ +-----+----+ + | | + X REQUEST | + X------------------------>X + | X + | REPLY X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | "DATA/STATE" X + *<------------------------X + | X + | CANCEL X + *------------------------>X + | X + | REPLY X + X<------------------------X + X | + + +.. important:: + + There is no guarantee that Service will not send more stream messages in time between CANCEL is sent, and REPLY to cancel request is received by the Client. However, the Service SHALL NOT send any stream message after it sends the REPLY to the CANCEL request. + +.. todo:: + :class: todo + + Describe additional transmission patterns. Especially ones for synchronous data transfer using ACK-REQUEST/ACK-REPLY flags. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. _ZMTP: https://rfc.zeromq.org/spec:23/ZMTP +.. _ROUTER: https://rfc.zeromq.org/spec:28/REQREP/ +.. _UUID: https://tools.ietf.org/html/rfc4122.html +.. _Protocol Buffers: https://developers.google.com/protocol-buffers/ +.. _Flat Buffers: https://github.com/google/flatbuffers +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSD| replace:: :doc:`3/FBSD` +.. |FBLP| replace:: :doc:`5/FBLP` +.. |SSTP| replace:: :doc:`6/SSTP` +.. |RSCFG| replace:: :doc:`7/RSCFG` +.. |RSCTRL| replace:: :doc:`8/RSCTRL` + diff --git a/rfc/5/FBLP.rst b/rfc/5/FBLP.rst new file mode 100644 index 0000000..7f7b500 --- /dev/null +++ b/rfc/5/FBLP.rst @@ -0,0 +1,76 @@ +##################################### +5/FBLP - Firebird Butler Log Protocol +##################################### + +:domain: github.com/FirebirdSQL/Butler +:shortname: 5/FBLP +:name: Firebird Butler Log Protocol +:status: raw +:editor: Pavel Císař + +Firebird Butler Log Protocol (FBLP) is designed for unified creation, processing, and exchange of log information within Firebird Butler system. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. important:: + + This specification is still incomplete (work in progress), hence the COSS change process is not yet fully applicable. All ideas and change proposals SHOULD be presented and discussed in `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Related Specifications +====================== + +#. :doc:`/rfc/3/FBSD` +#. :doc:`/rfc/4/FBSP` +#. :doc:`/rfc/6/SSTP` +#. :doc:`/rfc/7/RSCFG` +#. :doc:`/rfc/8/RSCTRL` + +1. Goals +======== + +The purpose of this specification is to define unified log format, and formal rules for exchanging log messages between Butler Service and its Client. Its goals are: + +#. Define unified, flexible and extensible data format for logging information, suitable for diagnostic and audit purposes. +#. Define serialization format for such logging information suitable for transmission in |FBSP| `Data Frames`. +#. Define the method of publishing log information through ZeroMQ_ PUB_ sockets. +#. Define a single API for forwarding log information between the :doc:`Firebird Butler Service ` and the `Client`. + +2. Implementation +================= + +.. todo:: + :class: todo + + Specification body. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. _ZMTP: https://rfc.zeromq.org/spec:23/ZMTP +.. _ZeroMQ: http://zeromq.org/ +.. _PUB: http://rfc.zeromq.org/spec:29/PUBSUB +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSD| replace:: :doc:`3/FBSD` +.. |FBSP| replace:: :doc:`4/FBSP` +.. |SSTP| replace:: :doc:`6/SSTP` +.. |RSCFG| replace:: :doc:`7/RSCFG` +.. |RSCTRL| replace:: :doc:`8/RSCTRL` + diff --git a/rfc/6/SSTP.rst b/rfc/6/SSTP.rst new file mode 100644 index 0000000..088adda --- /dev/null +++ b/rfc/6/SSTP.rst @@ -0,0 +1,76 @@ +############################### +6/SSTP - Service State Protocol +############################### + +:domain: github.com/FirebirdSQL/Butler +:shortname: 6/SSTP +:name: Service State Protocol +:status: raw +:editor: Pavel Císař + +Service State Protocol (SSTP) is designed for unified creation, processing, and exchange of Service state information within Firebird Butler system. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. important:: + + This specification is still incomplete (work in progress), hence the COSS change process is not yet fully applicable. All ideas and change proposals SHOULD be presented and discussed in `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Related Specifications +====================== + +#. :doc:`/rfc/3/FBSD` +#. :doc:`/rfc/4/FBSP` +#. :doc:`/rfc/5/FBLP` +#. :doc:`/rfc/7/RSCFG` +#. :doc:`/rfc/8/RSCTRL` + +1. Goals +======== + +The purpose of this specification is to define unified data format, and formal rules for exchanging state information between Butler Service and its Client. Its goals are: + +#. Define unified, flexible and extensible data format for `Service` and `Connection` state information, suitable for diagnostic and control purposes. +#. Define serialization format for such state information suitable for transmission in |FBSP| `Data Frames`. +#. Define the method of publishing such state information through ZeroMQ_ PUB_ sockets. +#. Define a base API for transmitting such state information between the :doc:`Firebird Butler Service ` and the `Client`. +#. Define a base API for changing the `Service` and `Connection` state by the `Client`. + +2. Implementation +================= + +.. todo:: + :class: todo + + Specification body. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. _ZeroMQ: http://zeromq.org/ +.. _PUB: http://rfc.zeromq.org/spec:29/PUBSUB +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSD| replace:: :doc:`3/FBSD` +.. |FBSP| replace:: :doc:`4/FBSP` +.. |FBLP| replace:: :doc:`5/FBLP` +.. |RSCFG| replace:: :doc:`7/RSCFG` +.. |RSCTRL| replace:: :doc:`8/RSCTRL` + diff --git a/rfc/7/RSCFG.rst b/rfc/7/RSCFG.rst new file mode 100644 index 0000000..9af1d1c --- /dev/null +++ b/rfc/7/RSCFG.rst @@ -0,0 +1,73 @@ +############################################### +7/RSCFG - Remote Service Configuration Protocol +############################################### + +:domain: github.com/FirebirdSQL/Butler +:shortname: 7/RSCFG +:name: Remote Service Configuration Protocol +:status: raw +:editor: Pavel Císař + +Remote Service Configuration Protocol (RSCFG) specifies a uniform method for configuring Firebird Butler Service operating parameters through Client requests passed via |FBSP| protocol. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. important:: + + This specification is still incomplete (work in progress), hence the COSS change process is not yet fully applicable. All ideas and change proposals SHOULD be presented and discussed in `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Related Specifications +====================== + +#. :doc:`/rfc/3/FBSD` +#. :doc:`/rfc/4/FBSP` +#. :doc:`/rfc/5/FBLP` +#. :doc:`/rfc/6/SSTP` +#. :doc:`/rfc/8/RSCTRL` + +1. Goals +======== + +The purpose of this specification is to define unified data format, and formal rules for exchanging configuration information between Butler Service and its Client. Its goals are: + +#. Define unified, flexible and extensible data format for `Service` configuration information, suitable for diagnostic and control purposes. +#. Define serialization format for such configuration information suitable for transmission in |FBSP| `Data Frames`. +#. Define a base API for transmitting such configuration information between the :doc:`Firebird Butler Service ` and the `Client`. +#. Define a base API for remote `Service` configuration by its `Client`. + +2. Implementation +================= + +.. todo:: + :class: todo + + Specification body. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSD| replace:: :doc:`3/FBSD` +.. |FBSP| replace:: :doc:`4/FBSP` +.. |FBLP| replace:: :doc:`5/FBLP` +.. |SSTP| replace:: :doc:`6/SSTP` +.. |RSCTRL| replace:: :doc:`8/RSCTRL` + diff --git a/rfc/8/RSCTRL.rst b/rfc/8/RSCTRL.rst new file mode 100644 index 0000000..6805301 --- /dev/null +++ b/rfc/8/RSCTRL.rst @@ -0,0 +1,73 @@ +########################################## +8/RSCTRL - Remote Service Control Protocol +########################################## + +:domain: github.com/FirebirdSQL/Butler +:shortname: 8/RSCTRL +:name: Remote Service Control Protocol +:status: raw +:editor: Pavel Císař + +Remote Service Control Protocol (RSCTRL) specifies a uniform method for controlling Firebird Butler Service operations through Client requests passed via |FBSP| protocol. + +License +======= + +Copyright (c) 2018 The Firebird Butler Project. + +This Specification is distributed under Creative Commons Attribution-ShareAlike 4.0 International license. + +You should have received a copy of the CC BY-SA 4.0 along with this document; if not, see https://creativecommons.org/licenses/by-sa/4.0/ + +Change Process +============== + +This Specification is a free and open standard and is governed by the Consensus-Oriented Specification System (COSS) (see "|COSS-long|"). + +.. important:: + + This specification is still incomplete (work in progress), hence the COSS change process is not yet fully applicable. All ideas and change proposals SHOULD be presented and discussed in `Firebird Butler forum `_. + +Language +======== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in `RFC2119`_. + +Related Specifications +====================== + +#. :doc:`/rfc/3/FBSD` +#. :doc:`/rfc/4/FBSP` +#. :doc:`/rfc/5/FBLP` +#. :doc:`/rfc/6/SSTP` +#. :doc:`/rfc/7/RSCFG` + +1. Goals +======== + +The purpose of this specification is to define unified data format, and formal rules for exchanging control messages between Butler Service and its Client. Its goals are: + +#. Define unified, flexible and extensible data format for control information, suitable for remote `Service` control purposes. +#. Define serialization format for such control information suitable for transmission in |FBSP| `Data Frames`. +#. Define a base API for transmitting such control information between the :doc:`Firebird Butler Service ` and the `Client`. +#. Define a base API for remote `Service` control by its `Client`. + +2. Implementation +================= + +.. todo:: + :class: todo + + Specification body. + +| +| + +.. _RFC2119: http://tools.ietf.org/html/rfc2119 +.. |COSS-long| replace:: :doc:`/rfc/2/COSS` +.. |FBSD| replace:: :doc:`3/FBSD` +.. |FBSP| replace:: :doc:`4/FBSP` +.. |FBLP| replace:: :doc:`5/FBLP` +.. |SSTP| replace:: :doc:`6/SSTP` +.. |RSCFG| replace:: :doc:`7/RSCFG` + diff --git a/rfc/rfc-index.rst b/rfc/rfc-index.rst new file mode 100644 index 0000000..9f91ea6 --- /dev/null +++ b/rfc/rfc-index.rst @@ -0,0 +1,14 @@ +######################### +Firebird Butler RFC Index +######################### + + +- :doc:`/rfc/1/C4` +- :doc:`/rfc/2/COSS` +- :doc:`/rfc/3/FBSD` +- :doc:`/rfc/4/FBSP` +- :doc:`/rfc/5/FBLP` +- :doc:`/rfc/6/SSTP` +- :doc:`/rfc/7/RSCFG` +- :doc:`/rfc/8/RSCTRL` + diff --git a/specifications.rst b/specifications.rst new file mode 100644 index 0000000..d92ca78 --- /dev/null +++ b/specifications.rst @@ -0,0 +1,65 @@ +############################## +Firebird Butler Specifications +############################## + +Specifications for APIs, file formats, wire protocols, and processes. + +The change process is :doc:`C4 ` with a few modifications: + +- A specification is created and modified by pull requests according to C4. +- Each specification has an editor who publishes the RFC to the `Butler repository`_ as needed. +- Specification lifecycle SHOULD follow the lifecycle defined in :doc:`2/COSS ` +- Non-cosmetic changes are allowed only on Raw and Draft specifications. + + + +.. toctree:: + :maxdepth: 1 + :hidden: + + rfc/rfc-index + + +Raw +=== + +.. toctree:: + :maxdepth: 1 + + /rfc/3/FBSD + /rfc/4/FBSP + /rfc/5/FBLP + /rfc/6/SSTP + /rfc/7/RSCFG + /rfc/8/RSCTRL + +Draft +===== + +.. toctree:: + :maxdepth: 1 + + /rfc/1/C4 + /rfc/2/COSS + +Stable +====== + +None at this time. + +Deprecated +========== + +None at this time. + +Retired +======= + +None at this time. + +Deleted +======= + +None at this time. + +.. _Butler repository: https://github.com/FirebirdSQL/Butler