ridv/gorealis
1
0
Fork 0
Code Issues Pull requests Projects Releases 23 Packages Wiki Activity Actions

Moving from govendor to dep, updated dependencies (#48)

Browse source 
* Moving from govendor to dep.

* Making the pull request template more friendly.

* Fixing akward space in PR template.

* goimports run on whole project using ` goimports -w $(find . -type f -name '*.go' -not -path "./vendor/*" -not -path "./gen-go/*")`

source of command: https://gist.github.com/bgentry/fd1ffef7dbde01857f66
This commit is contained in:
Renan DelValle 2018-01-07 13:13:47 -08:00 • committed by GitHub
parent 9631aa3aab
commit 8d445c1c77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2186 changed files with 400410 additions and 352 deletions
Download patch file Download diff file Expand all files Collapse all files

48
vendor/git.apache.org/thrift.git/doc/coding_standards.md generated vendored Normal file
View file

@ -0,0 +1,48 @@
# Thrift Coding Standards
Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.
-- Martin Fowler, 1999
The purpose of this document is to make everyone's life easier.
It's easier when you read good, well formatted, with clearly defined purpose, code.
But the only way to read clean code is to write such.
This document can help achieve that, but keep in mind that
those are not silver-bullet, fix-all-at-once rules. Just think about readability while writing code.
Write code like you would have to read it in ten years from now.
## General Coding Standards
Thrift has some history. Not all existing code follows those rules.
But we want to improve over time.
When making small change / bugfix - like single line fix - do *not* refactor whole function.
That disturbs code repository history.
Whenever adding something new and / or making bigger refactoring
- follow those rules as strictly as you can.
When in doubt - contact other developers (using dev@ mailing list or IRC).
Code review is the best way to improve readability.
### Basics
* Use spaces not tabs
* Use only ASCII characters in file and directory names
* Commit to repository using Unix-style line endings (LF)
On Windows:
git config core.autocrlf true
* Maximum line width - 100 characters
* If not specified otherwise in language specific standard - use 2 spaces as indent/tab
### Comments
* Each file has to start with comment containing [Apache License](http://www.apache.org/licenses/LICENSE-2.0)
* Public API of library should be documented, preferably using format native for language specific documentation generation tools (Javadoc, Doxygen etc.)
* Other comments are discouraged - comments are lies. When one has to make comment it means one failed to write readable code. Instead of "I should write a comment here" think "I should clean it up"
* Do not leave "TODO/FIXME" comments - file [Jira](http://issues.apache.org/jira/browse/THRIFT) issue instead
### Naming
Finding proper names is the most important and most difficult task in software development.
## Language Specific Coding Standards
For detailed information see `lib/LANG/coding_standards.md`

54
vendor/git.apache.org/thrift.git/doc/committers.md generated vendored Normal file
View file

@ -0,0 +1,54 @@
## Process used by committers to review and submit patches
1. Make sure that there is an issue for the patch(s) you are about to commit in our [Jira issue tracker](http://issues.apache.org/jira/browse/THRIFT)
1. Check out the latest version of the source code
* git clone https://git-wip-us.apache.org/repos/asf/thrift.git thrift
1. Apply the patch
* curl https://issues.apache.org/jira/... |git apply --ignore-space-change
or
* curl https://github.com/<GitHub User>/thrift/commit/<Commit ID>.patch |git apply --ignore-space-change
1. Inspect the applied patch to ensure that all [Legal aspects on Submission of Contributions (Patches)](http://www.apache.org/licenses/LICENSE-2.0.html#contributions) are met
1. Run the necessary unit tests and cross language test cases to verify the patch
1. Commit the patch
git --config user.name "Your Name"
git --config user.email "YourApacheID@apache.org"
git add -A
git commit
1. The commit message should be in the format:
THRIFT-###:<Jira description>
Client: <component>
Patch: <Name of person contributing the patch>
Description of what was fixed or addressed.
<%
if this is a github pull request then add below comment
to automaticaly close GitHub request.
%>
This closes #XX
1. Double check the patch committed and that nothing was missed then push the patch
git status
git show HEAD
git push origin master
1. Resolve the jira issue and set the following for the changelog
* Component the patch is for
* fixVersion to the current version on master

43
vendor/git.apache.org/thrift.git/doc/install/README.md generated vendored Normal file
View file

@ -0,0 +1,43 @@
## Basic requirements
* A relatively POSIX-compliant *NIX system
* Cygwin or MinGW can be used on Windows (but there are better options, see below)
* g++ 4.2
* boost 1.53.0
* Runtime libraries for lex and yacc might be needed for the compiler.
## Requirements for building from source
* GNU build tools:
* autoconf 2.65
* automake 1.13
* libtool 1.5.24
* pkg-config autoconf macros (pkg.m4)
* lex and yacc (developed primarily with flex and bison)
* libssl-dev
## Requirements for building the compiler from source on Windows
* Visual Studio C++
* Flex and Bison (e.g. the WinFlexBison package)
## Language requirements
These are only required if you choose to build the libraries for the given language
* C++
* Boost 1.53.0
* libevent (optional, to build the nonblocking server)
* zlib (optional)
* Java
* Java 1.7
* Apache Ant
* C#: Mono 1.2.4 (and pkg-config to detect it) or Visual Studio 2005+
* Python 2.6 (including header files for extension modules)
* PHP 5.0 (optionally including header files for extension modules)
* Ruby 1.8
* bundler gem
* Erlang R12 (R11 works but not recommended)
* Perl 5
* Bit::Vector
* Class::Accessor
* Haxe 3.1.3
* Go 1.4
* Delphi 2010

75
vendor/git.apache.org/thrift.git/doc/install/centos.md generated vendored Normal file
View file

@ -0,0 +1,75 @@
# Building Apache Thrift on CentOS 6.5
Starting with a minimal installation, the following steps are required to build Apache Thrift on Centos 6.5. This example builds from source, using the current development master branch. These instructions should also work with Apache Thrift releases beginning with 0.9.2.
## Update the System
sudo yum -y update
## Install the Platform Development Tools
sudo yum -y groupinstall "Development Tools"
## Upgrade autoconf/automake/bison
sudo yum install -y wget
### Upgrade autoconf
wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz
tar xvf autoconf-2.69.tar.gz
cd autoconf-2.69
./configure --prefix=/usr
make
sudo make install
cd ..
### Upgrade automake
wget http://ftp.gnu.org/gnu/automake/automake-1.14.tar.gz
tar xvf automake-1.14.tar.gz
cd automake-1.14
./configure --prefix=/usr
make
sudo make install
cd ..
### Upgrade bison
wget http://ftp.gnu.org/gnu/bison/bison-2.5.1.tar.gz
tar xvf bison-2.5.1.tar.gz
cd bison-2.5.1
./configure --prefix=/usr
make
sudo make install
cd ..
## Add Optional C++ Language Library Dependencies
All languages require the Apache Thrift IDL Compiler and at this point everything needed to make the IDL Compiler is installed (if you only need the compiler you can skip to the Build step).
If you will be developing Apache Thrift clients/servers in C++ you will also need additional packages to support the C++ shared library build.
### Install C++ Lib Dependencies
sudo yum -y install libevent-devel zlib-devel openssl-devel
### Upgrade Boost >= 1.53
wget http://sourceforge.net/projects/boost/files/boost/1.53.0/boost_1_53_0.tar.gz
tar xvf boost_1_53_0.tar.gz
cd boost_1_53_0
./bootstrap.sh
sudo ./b2 install
## Build and Install the Apache Thrift IDL Compiler
git clone https://git-wip-us.apache.org/repos/asf/thrift.git
cd thrift
./bootstrap.sh
./configure --with-lua=no
make
sudo make install
This will build the compiler (thrift/compiler/cpp/thrift --version) and any language libraries supported. The make install step installs the compiler on the path: /usr/local/bin/thrift
You can use the ./configure --enable-libs=no switch to build the Apache Thrift IDL Compiler only without lib builds. To run tests use "make check".

46
vendor/git.apache.org/thrift.git/doc/install/debian.md generated vendored Normal file
View file

@ -0,0 +1,46 @@
## Debian/Ubuntu install
The following command will install tools and libraries required to build and install the Apache Thrift compiler and C++ libraries on a Debian/Ubuntu Linux based system.
sudo apt-get install automake bison flex g++ git libboost1.55-all-dev libevent-dev libssl-dev libtool make pkg-config
Debian 7/Ubuntu 12 users need to manually install a more recent version of automake and (for C++ library and test support) boost:
wget http://ftp.debian.org/debian/pool/main/a/automake-1.15/automake_1.15-3_all.deb
sudo dpkg -i automake_1.15-3_all.deb
wget http://sourceforge.net/projects/boost/files/boost/1.60.0/boost_1_60_0.tar.gz tar xvf boost_1_60_0.tar.gz
cd boost_1_60_0
./bootstrap.sh
sudo ./b2 install
## Optional packages
If you would like to build Apache Thrift libraries for other programming languages you may need to install additional packages. The following languages require the specified additional packages:
* Java
* To build Apache Thrift support for Java you will need to install the ant package and Java JDK v1.7 or higher. Type **javac** to see a list of available packages, pick the one you prefer and **apt-get install** it (e.g. openjdk-7-jdk).
* Ruby
* ruby-full ruby-dev ruby-rspec rake rubygems libdaemons-ruby libgemplugin-ruby mongrel
* Python
* python-all python-all-dev python-all-dbg
* Perl
* libbit-vector-perl libclass-accessor-class-perl
* Php, install
* php5-dev php5-cli phpunit
* C_glib
* libglib2.0-dev
* Erlang
* erlang-base erlang-eunit erlang-dev
* Csharp
* mono-gmcs mono-devel libmono-system-web2.0-cil nunit nunit-console
* Haskell
* ghc6 cabal-install libghc6-binary-dev libghc6-network-dev libghc6-http-dev
* Thrift Compiler for Windows
* mingw32 mingw32-binutils mingw32-runtime nsis
## Additional reading
For more information on the requirements see: [Apache Thrift Requirements](/docs/install)
For more information on building and installing Thrift see: [Building from source](/docs/BuildingFromSource)

27
vendor/git.apache.org/thrift.git/doc/install/os_x.md generated vendored Normal file
View file

@ -0,0 +1,27 @@
## OS X Setup
The following command install all the required tools and libraries to build and install the Apache Thrift compiler on a OS X based system.
### Install Boost
Download the boost library from [boost.org](http://www.boost.org) untar compile with
./bootstrap.sh
sudo ./b2 threading=multi address-model=64 variant=release stage install
### Install libevent
Download [libevent](http://monkey.org/~provos/libevent), untar and compile with
./configure --prefix=/usr/local
make
sudo make install
### Building Apache Thrift
Download the latest version of [Apache Thrift](/download), untar and compile with
./configure --prefix=/usr/local/ --with-boost=/usr/local --with-libevent=/usr/local
## Additional reading
For more information on the requirements see: [Apache Thrift Requirements](/docs/install)
For more information on building and installing Thrift see: [Building from source](/docs/BuildingFromSource)

186
vendor/git.apache.org/thrift.git/doc/install/windows.md generated vendored Normal file
View file

@ -0,0 +1,186 @@
## Windows Setup
The Thrift environment consists of two main parts: The Thrift compiler EXE and the language-dependent libraries. Most of these libraries will require some kind of build and/or installation. But regarding the Thrift compiler utility there are a number of different alternatives.
The first one of these alternatives is to download the **pre-built Thrift Compiler EXE** and only build the libraries needed from source, following one of the "Setup from source" methods outlined below.
The other two options are to build the Thrift compiler from source. The most recommended way to achieve this is by means of the **Visual Studio C++ build project**. Alternatively, the Thrift compiler can also be built via **Cygwin** or **MinGW** build environments, however this method is not only less comfortable, but more time-consuming and requires much more manual effort.
## Prebuilt Thrift compiler
The windows Thrift compiler is available as a prebuilt exe available [here](/download). Note that there is no installation tool, rather this EXE file *is* already the Thrift compiler utility. Download the file and put it into some suitable location of your choice.
Now pick one of the "Build and install target libraries" below to continue.
## Setup from source via Visual Studio C++ (recommended)
### Requirements
Thrift's compiler is written in C++ and designed to be portable, but there are some system requirements. Thrift's runtime libraries are written in various languages, which are also required for the particular language interface.
* Visual Studio C++, any recent version should do
* Flex and Bison, e.g. the WinFlexBison package
* [Apache Thrift Requirements](/docs/install)
### Build and install the compiler
After all requirements are in place, use the `compiler/cpp/compiler.vcxproj` build project to build the Thrift compiler. Copy the resulting EXE file to a location of your choice.
### Build and install target libraries
A few of the target language libraries also do provide Visual Studio project files, such as C++ and C#. These are located in the `lib/<language>/` folders.
Most of the language packages must be built and installed manually using build tools better suited to those languages. Typical examples are Java, Ruby, Delphi, or PHP. Look for the `README.md` file in the `lib/<language>/` folder for more details on how to build and install each language's library package.
## Setup from source via Cygwin
### Requirements
Thrift's compiler is written in C++ and designed to be portable, but there are some system requirements. Thrift's runtime libraries are written in various languages, which are also required for the particular language interface.
* Cygwin or MinGW
* [Apache Thrift Requirements](/docs/install)
### Installing from source
If you are building from the first time out of the source repository, you will need to generate the configure scripts. (This is not necessary if you downloaded a tarball.) From the top directory, do:
./bootstrap.sh
Once the configure scripts are generated, thrift can be configured. From the top directory, do:
export CXXFLAGS="-D PTHREAD_MUTEX_RECURSIVE_NP=PTHREAD_MUTEX_RECURSIVE"
./configure
Setting the CXXFLAGS environmental variable works around compile errors with PTHREAD_MUTEX_RECURSIVE_NP being undeclared, by replacing it with the newer, portable PTHREAD_MUTEX_RECURSIVE. (Tested on cygwin 20100320, Thrift r760184, latest pthread.)
**Optional:** You **may not** be able to make from the root Thrift directory due to errors (see below to resolve). To make the compiler only, change to the compiler directory before running make:
cd compiler/cpp
Now make the thrift compiler (& runtime libraries if make is run from the thrift root directory):
make
make install
### Build and install target libraries
Some language packages must be installed manually using build tools better suited to those languages. Typical examples are Java, Ruby, or PHP. Look for the README file in the `lib/<language>/` folder for more details on the installation of each language library package.
### Possible issues with Cygwin install
See also Possible issues with MinGW install.
#### Syntax error in ./configure
The following error occurs for some users when running ./configure:
./configure: line 21183: syntax error near unexpected token `MONO,'
./configure: line 21183: ` PKG_CHECK_MODULES(MONO, mono >= 1.2.6, have_mono=yes, have_mono=no)'
To resolve this, you'll need to find your pkg.m4 (installed by the pkg-config package) file and copy it to the thrift/aclocal directory. From the top-level thrift directory, you can copy the file by running
cp /usr/share/aclocal/pkg.m4 aclocal
Finally, re-run ./bootstrap.sh and ./configure. (Note that pkg.m4 is created by the pkg-config tool. If your /usr/share/aclocal directory doesn't contain the pkg.m4 file, you may not have pkg-config installed.)
#### Installing perl runtime libraries
Sometimes, there will be an error during the install of the perl libraries with chmod.
A workaround is to avoid installing the perl libraries if they are not needed.
If you don't need perl, run configure with --without-perl.
If you need perl, and are happy to manually install it, replace the contents of thrift/lib/perl/Makefile with the following, after building thrift:
TODO
#### Linking to installed C++ runtime libraries
Sometimes, the installed libthrift.a will not link using g++, with linker errors about missing vtables and exceptions for Thrift classes.
A workaround is to link the compiled object files directly from your Thrift build, corresponding to the missing classes.
This can be implemented in a Makefile using the following lines:
THRIFT_O=<path to>/thrift/lib/cpp
LTHRIFT=$(THRIFT_O)/Thrift.o $(THRIFT_O)/TSocket.o $(THRIFT_O)/TBinaryProtocol.o $(THRIFT_O)/TBufferTransports.o
Then linking using $(LTHRIFT) instead of -lthrift.
TODO - diagnose issue further
#### C++ runtime segfault with cygwin 1.7.5-1, g++-4.3.4, fork() and throw
If your thrift C++ programs segfault on throw after fork()ing, compile them with g++-3.
The issue and patch are described on the Cygwin mailing list at http://cygwin.com/ml/cygwin/2010-05/msg00203.html
This issue should be fixed in Cygwin versions after 1.7.5-1, or g++ 4.5.0.
## Setup from source via MinGW
### Requirements
To compile the Thrift generator & runtime libraries (untested) without the cygwin.dll dependency you need to install MinGW (www.mingw.org).
* MinGW
* [Apache Thrift Requirements](/docs/install)
In addition you need to add the following entry to your windows PATH variable.
C:\MINGW\BIN
Next, open compiler/cpp/Makefile.am and add the following line to thrift_CXXFLAGS
-DMINGW -mno-cygwin -lfl
Run bootstrap.sh:
./bootstrap.sh
Make sure you have java in your $PATH variable, if not do(adjust path if necessary):
export PATH=$PATH:"/cygdrive/c/program files/java/jre1.6.0_05/bin"
Run configure - using CXXFLAGS to work around an issue with an old pthreads define (untested on MinGW - works on Cygwin):
export CXXFLAGS="-D PTHREAD_MUTEX_RECURSIVE_NP=PTHREAD_MUTEX_RECURSIVE"
./configure
''Optional:'' To make the compiler only, change to the compiler directory before running make:
cd compiler/cpp
Run make:
mingw32-make.exe
### Possible issues with MinGW install
See also Possible issues with Cygwin install, including the discussion about PTHREAD_MUTEX_RECURSIVE_NP.
#### yywrap is not found
Make sure you add -lfl in your cxxflags in Makefile, also try adding -Lc:/cygwin/libs
#### boost is not found
Try and change the include dir to use the windows path from c like this: Edit compiler/cpp/Makefile, look for the declaration of BOOST_CPPFLAGS, change that line for
BOOST_CPPFLAGS = -Ic:/cygwin/usr/include/boost-1_53_0
#### realpath is not found
add -DMINGW -mno-cygwin to the CXXDEFS variable in Makefile
## Additional reading
For more information on the requirements see: [Apache Thrift Requirements](/docs/install)
For more information on building and installing Thrift see: [Building from source](/docs/BuildingFromSource)

504
vendor/git.apache.org/thrift.git/doc/licenses/lgpl-2.1.txt generated vendored Normal file
View file

@ -0,0 +1,504 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library 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
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!

20
vendor/git.apache.org/thrift.git/doc/licenses/otp-base-license.txt generated vendored Normal file
View file

@ -0,0 +1,20 @@
Tue Oct 24 12:28:44 CDT 2006
Copyright (c) <2006> <Martin J. Logan, Erlware>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software (OTP Base, fslib, G.A.S) and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

82
vendor/git.apache.org/thrift.git/doc/specs/HeaderFormat.md generated vendored Normal file
View file

@ -0,0 +1,82 @@
<link href="http://kevinburke.bitbucket.org/markdowncss/markdown.css" rel="stylesheet"></link>
Header format for the THeader.h
===============================
0 1 2 3 4 5 6 7 8 9 a b c d e f 0 1 2 3 4 5 6 7 8 9 a b c d e f
+----------------------------------------------------------------+
| 0| LENGTH |
+----------------------------------------------------------------+
| 0| HEADER MAGIC | FLAGS |
+----------------------------------------------------------------+
| SEQUENCE NUMBER |
+----------------------------------------------------------------+
| 0| Header Size(/32) | ...
+---------------------------------
Header is of variable size:
(and starts at offset 14)
+----------------------------------------------------------------+
| PROTOCOL ID (varint) | NUM TRANSFORMS (varint) |
+----------------------------------------------------------------+
| TRANSFORM 0 ID (varint) | TRANSFORM 0 DATA ...
+----------------------------------------------------------------+
| ... ... |
+----------------------------------------------------------------+
| INFO 0 ID (varint) | INFO 0 DATA ...
+----------------------------------------------------------------+
| ... ... |
+----------------------------------------------------------------+
| |
| PAYLOAD |
| |
+----------------------------------------------------------------+
The `LENGTH` field is 32 bits, and counts the remaining bytes in the
packet, NOT including the length field. The header size field is 16
bits, and defines the size of the header remaining NOT including the
`HEADER MAGIC`, `FLAGS`, `SEQUENCE NUMBER` and header size fields. The
Header size field is in bytes/4.
The transform ID's are varints. The data for each transform is
defined by the transform ID in the code - no size is given in the
header. If a transform ID is specified from a client and the server
doesn't know about the transform ID, an error MUST be returned as we
don't know how to transform the data.
Conversely, data in the info headers is ignorable. This should only
be things like timestamps, debuging tracing, etc. Using the header
size you should be able to skip this data and read the payload safely
if you don't know the info ID.
Info's should be oldest supported to newest supported order, so that
if we read an info ID we don't support, none of the remaining info
ID's will be supported either, and we can safely skip to the payload.
Info ID's and transform ID's should share the same ID space.
### PADDING:
Header will be padded out to next 4-byte boundary with `0x00`.
Max frame size is `0x3FFFFFFF`, which is slightly less than `HTTP_MAGIC`.
This allows us to distingush between different (older) transports.
### Transform IDs:
ZLIB_TRANSFORM 0x01 - No data for this. Use zlib to (de)compress the
data.
HMAC_TRANSFORM 0x02 - Variable amount of mac data. One byte to specify
size. Mac data is appended at the end of the packet.
SNAPPY_TRANSFORM 0x03 - No data for this. Use snappy to (de)compress the
data.
###Info IDs:
INFO_KEYVALUE 0x01 - varint32 number of headers.
- key/value pairs of varstrings (varint16 length plus
no-trailing-null string).

272
vendor/git.apache.org/thrift.git/doc/specs/idl.md generated vendored Normal file
View file

@ -0,0 +1,272 @@
## Thrift interface description language
The Thrift interface definition language (IDL) allows for the definition of [Thrift Types](/docs/types). A Thrift IDL file is processed by the Thrift code generator to produce code for the various target languages to support the defined structs and services in the IDL file.
## Description
*Under construction*
Here is a description of the Thrift IDL.
## Document
Every Thrift document contains 0 or more headers followed by 0 or more definitions.
[1] Document ::= Header* Definition*
## Header
A header is either a Thrift include, a C++ include, or a namespace declaration.
[2] Header ::= Include | CppInclude | Namespace
### Thrift Include
An include makes all the symbols from another file visible (with a prefix) and adds corresponding include statements into the code generated for this Thrift document.
[3] Include ::= 'include' Literal
### C++ Include
A C++ include adds a custom C++ include to the output of the C++ code generator for this Thrift document.
[4] CppInclude ::= 'cpp_include' Literal
### Namespace
A namespace declares which namespaces/package/module/etc. the type definitions in this file will be declared in for the target languages. The namespace scope indicates which language the namespace applies to; a scope of '*' indicates that the namespace applies to all target languages.
[5] Namespace ::= ( 'namespace' ( NamespaceScope Identifier ) |
( 'smalltalk.category' STIdentifier ) |
( 'smalltalk.prefix' Identifier ) ) |
( 'php_namespace' Literal ) |
( 'xsd_namespace' Literal )
[6] NamespaceScope ::= '*' | 'cpp' | 'java' | 'py' | 'perl' | 'rb' | 'cocoa' | 'csharp'
N.B.: Smalltalk has two distinct types of namespace commands:
- smalltalk.prefix: Prepended to generated classnames.
- Smalltalk does not have namespaces for classes, so prefixes
are used to avoid class-name collisions.
Often, the prefix is the author's initials, like "KB" or "JWS",
or an abbreviation of the package name, like "MC" for "Monticello".
- smalltalk.category: Determines the category for generated classes.
Any dots in the identifier will be replaced with hyphens when generating
the category name.
If not provided, defaults to "Generated-" + the program name.
Methods will not be categorized beyond "as yet uncategorized".
- Smalltalk allows filing both classes and methods within classes into named
groups. These named groups of methods are called categories.
N.B.: The `php_namespace` directive will be deprecated at some point in the future in favor of the scoped syntax, but the scoped syntax is not yet supported for PHP.
N.B.: The `xsd_namespace` directive has some purpose internal to Facebook but serves no purpose in Thrift itself. Use of this feature is strongly discouraged
## Definition
[7] Definition ::= Const | Typedef | Enum | Senum | Struct | Union | Exception | Service
### Const
[8] Const ::= 'const' FieldType Identifier '=' ConstValue ListSeparator?
### Typedef
A typedef creates an alternate name for a type.
[9] Typedef ::= 'typedef' DefinitionType Identifier
### Enum
An enum creates an enumerated type, with named values. If no constant value is supplied, the value is either 0 for the first element, or one greater than the preceding value for any subsequent element. Any constant value that is supplied must be non-negative.
[10] Enum ::= 'enum' Identifier '{' (Identifier ('=' IntConstant)? ListSeparator?)* '}'
### Senum
Senum (and Slist) are now deprecated and should both be replaced with String.
[11] Senum ::= 'senum' Identifier '{' (Literal ListSeparator?)* '}'
### Struct
Structs are the fundamental compositional type in Thrift. The name of each field must be unique within the struct.
[12] Struct ::= 'struct' Identifier 'xsd_all'? '{' Field* '}'
N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no purpose in Thrift itself. Use of this feature is strongly discouraged
### Union
Unions are similar to structs, except that they provide a means to transport exactly one field of a possible set of fields, just like union {} in C++. Consequently, union members are implicitly considered optional (see requiredness).
[13] Union ::= 'union' Identifier 'xsd_all'? '{' Field* '}'
N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no purpose in Thrift itself. Use of this feature is strongly discouraged
### Exception
Exceptions are similar to structs except that they are intended to integrate with the native exception handling mechanisms in the target languages. The name of each field must be unique within the exception.
[14] Exception ::= 'exception' Identifier '{' Field* '}'
### Service
A service provides the interface for a set of functionality provided by a Thrift server. The interface is simply a list of functions. A service can extend another service, which simply means that it provides the functions of the extended service in addition to its own.
[15] Service ::= 'service' Identifier ( 'extends' Identifier )? '{' Function* '}'
## Field
[16] Field ::= FieldID? FieldReq? FieldType Identifier ('= ConstValue)? XsdFieldOptions ListSeparator?
### Field ID
[17] FieldID ::= IntConstant ':'
### Field Requiredness
There are two explicit requiredness values, and a third one that is applied implicity if neither *required* nor *optional* are given: *default* requiredness.
[18] FieldReq ::= 'required' | 'optional'
The general rules for requiredness are as follows:
#### required
- Write: Required fields are always written and are expected to be set.
- Read: Required fields are always read and are expected to be contained in the input stream.
- Defaults values: are always written
If a required field is missing during read, the expected behaviour is to indicate an unsuccessful read operation to the caller, e.g. by throwing an exception or returning an error.
Because of this behaviour, required fields drastically limit the options with regard to soft versioning. Because they must be present on read, the fields cannot be deprecated. If a required field would be removed (or changed to optional), the data are no longer compatible between versions.
#### optional
- Write: Optional fields are only written when they are set
- Read: Optional fields may, or may not be part of the input stream.
- Default values: are written when the isset flag is set
Most language implementations use the recommended pratice of so-called "isset" flags to indicate whether a particular optional field is set or not. Only fields with this flag set are written, and conversely the flag is only set when a field value has been read from the input stream.
#### default requiredness (implicit)
- Write: In theory, the fields are always written. There are some exceptions to that rule, see below.
- Read: Like optional, the field may, or may not be part of the input stream.
- Default values: may not be written (see next section)
Default requiredess is a good starting point. The desired behaviour is a mix of optional and required, hence the internal name "opt-in, req-out". Although in theory these fields are supposed to be written ("req-out"), in reality unset fields are not always written. This is especially the case, when the field contains a <null> value, which by definition cannot be transported through thrift. The only way to achieve this is by not writing that field at all, and that's what most languages do.
#### Semantics of Default Values
There are ongoing discussions about that topic, see JIRA for details. Not all implementations treat default values in the very same way, but the current status quo is more or less that default fields are typically set at initialization time. Therefore, a value that equals the default may not be written, because the read end will set the value implicitly. On the other hand, an implementation is free to write the default value anyways, as there is no hard restriction that prevents this.
The major point to keep in mind here is the fact, that any unwritten default value implicitly becomes part of the interface version. If that default is changed, the interface changes. If, in contrast, the default value is written into the output data, the default in the IDL can change at any time without affecting serialized data.
### XSD Options
N.B.: These have some internal purpose at Facebook but serve no current purpose in Thrift. Use of these options is strongly discouraged.
[19] XsdFieldOptions ::= 'xsd_optional'? 'xsd_nillable'? XsdAttrs?
[20] XsdAttrs ::= 'xsd_attrs' '{' Field* '}'
## Functions
[21] Function ::= 'oneway'? FunctionType Identifier '(' Field* ')' Throws? ListSeparator?
[22] FunctionType ::= FieldType | 'void'
[23] Throws ::= 'throws' '(' Field* ')'
## Types
[24] FieldType ::= Identifier | BaseType | ContainerType
[25] DefinitionType ::= BaseType | ContainerType
[26] BaseType ::= 'bool' | 'byte' | 'i8' | 'i16' | 'i32' | 'i64' | 'double' | 'string' | 'binary' | 'slist'
[27] ContainerType ::= MapType | SetType | ListType
[28] MapType ::= 'map' CppType? '<' FieldType ',' FieldType '>'
[29] SetType ::= 'set' CppType? '<' FieldType '>'
[30] ListType ::= 'list' '<' FieldType '>' CppType?
[31] CppType ::= 'cpp_type' Literal
## Constant Values
[32] ConstValue ::= IntConstant | DoubleConstant | Literal | Identifier | ConstList | ConstMap
[33] IntConstant ::= ('+' | '-')? Digit+
[34] DoubleConstant ::= ('+' | '-')? Digit* ('.' Digit+)? ( ('E' | 'e') IntConstant )?
[35] ConstList ::= '[' (ConstValue ListSeparator?)* ']'
[36] ConstMap ::= '{' (ConstValue ':' ConstValue ListSeparator?)* '}'
## Basic Definitions
### Literal
[37] Literal ::= ('"' [^"]* '"') | ("'" [^']* "'")
### Identifier
[38] Identifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' )*
[39] STIdentifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' | '-' )*
### List Separator
[40] ListSeparator ::= ',' | ';'
### Letters and Digits
[41] Letter ::= ['A'-'Z'] | ['a'-'z']
[42] Digit ::= ['0'-'9']
## Examples
Here are some examples of Thrift definitions, using the Thrift IDL:
* [ThriftTest.thrift][] used by the Thrift TestFramework
* Thrift [tutorial][]
* Facebook's [fb303.thrift][]
* [Apache Cassandra's][] Thrift IDL: [cassandra.thrift][]
* [Evernote API][]
[ThriftTest.thrift]: https://git-wip-us.apache.org/repos/asf?p=thrift.git;a=blob_plain;f=test/ThriftTest.thrift;hb=HEAD
[tutorial]: /tutorial/
[fb303.thrift]: https://git-wip-us.apache.org/repos/asf?p=thrift.git;a=blob_plain;f=contrib/fb303/if/fb303.thrift;hb=HEAD
[Apache Cassandra's]: http://cassandra.apache.org/
[cassandra.thrift]: http://svn.apache.org/viewvc/cassandra/trunk/interface/cassandra.thrift?view=co
[Evernote API]: http://www.evernote.com/about/developer/api/
## To Do/Questions
Initialization of Base Types for all Languages?
* Do all Languages initialize them to 0, bool=false and string=""? or null, undefined?
Why does position of `CppType` vary between `SetType` and `ListType`?
* std::set does sort the elements automatically, that's the design. see [Thrift Types](/docs/types) or the [C++ std:set reference][] for further details
* The question is, how other languages are doing that? What about custom objects, do they have a Compare function the set the order correctly?
[C++ std:set reference]: http://www.cplusplus.com/reference/stl/set/
Why can't `DefinitionType` be the same as `FieldType` (i.e. include `Identifier`)?
Examine the `smalltalk.prefix` and `smalltalk.category` status (esp `smalltalk.category`, which takes `STIdentifier` as its argument)...
What to do about `ListSeparator`? Do we really want to be as lax as we currently are?
Should `Field*` really be `Field+` in `Struct`, `Enum`, etc.?

254
vendor/git.apache.org/thrift.git/doc/specs/thrift-binary-protocol.md generated vendored Normal file
View file

@ -0,0 +1,254 @@
Thrift Binary protocol encoding
===============================
<!--
--------------------------------------------------------------------
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
--------------------------------------------------------------------
-->
This documents describes the wire encoding for RPC using the older Thrift *binary protocol*.
The information here is _mostly_ based on the Java implementation in the Apache thrift library (version 0.9.1 and
0.9.3). Other implementation however, should behave the same.
For background on Thrift see the [Thrift whitepaper (pdf)](https://thrift.apache.org/static/files/thrift-20070401.pdf).
# Contents
* Binary protocol
* Base types
* Message
* Struct
* List and Set
* Map
* BNF notation used in this document
# Binary protocol
## Base types
### Integer encoding
In the _binary protocol_ integers are encoded with the most significant byte first (big endian byte order, aka network
order). An `int8` needs 1 byte, an `int16` 2, an `int32` 4 and an `int64` needs 8 bytes.
The CPP version has the option to use the binary protocol with little endian order. Little endian gives a small but
noticeable performance boost because contemporary CPUs use little endian when storing integers to RAM.
### Enum encoding
The generated code encodes `Enum`s by taking the ordinal value and then encoding that as an int32.
### Binary encoding
Binary is sent as follows:
```
Binary protocol, binary data, 4+ bytes:
+--------+--------+--------+--------+--------+...+--------+
| byte length | bytes |
+--------+--------+--------+--------+--------+...+--------+
```
Where:
* `byte length` is the length of the byte array, a signed 32 bit integer encoded in network (big endian) order (must be >= 0).
* `bytes` are the bytes of the byte array.
### String encoding
*String*s are first encoded to UTF-8, and then send as binary.
### Double encoding
Values of type `double` are first converted to an int64 according to the IEEE 754 floating-point "double format" bit
layout. Most run-times provide a library to make this conversion. Both the binary protocol as the compact protocol then
encode the int64 in 8 bytes in big endian order.
### Boolean encoding
Values of `bool` type are first converted to an int8. True is converted to `1`, false to `0`.
## Message
A `Message` can be encoded in two different ways:
```
Binary protocol Message, strict encoding, 12+ bytes:
+--------+--------+--------+--------+--------+--------+--------+--------+--------+...+--------+--------+--------+--------+--------+
|1vvvvvvv|vvvvvvvv|unused |00000mmm| name length | name | seq id |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+...+--------+--------+--------+--------+--------+
```
Where:
* `vvvvvvvvvvvvvvv` is the version, an unsigned 15 bit number fixed to `1` (in binary: `000 0000 0000 0001`).
The leading bit is `1`.
* `unused` is an ignored byte.
* `mmm` is the message type, an unsigned 3 bit integer. The 5 leading bits must be `0` as some clients (checked for
java in 0.9.1) take the whole byte.
* `name length` is the byte length of the name field, a signed 32 bit integer encoded in network (big endian) order (must be >= 0).
* `name` is the method name, a UTF-8 encoded string.
* `seq id` is the sequence id, a signed 32 bit integer encoded in network (big endian) order.
The second, older encoding (aka non-strict) is:
```
Binary protocol Message, old encoding, 9+ bytes:
+--------+--------+--------+--------+--------+...+--------+--------+--------+--------+--------+--------+
| name length | name |00000mmm| seq id |
+--------+--------+--------+--------+--------+...+--------+--------+--------+--------+--------+--------+
```
Where `name length`, `name`, `mmm`, `seq id` are as above.
Because `name length` must be positive (therefore the first bit is always `0`), the first bit allows the receiver to see
whether the strict format or the old format is used. Therefore a server and client using the different variants of the
binary protocol can transparently talk with each other. However, when strict mode is enforced, the old format is
rejected.
Message types are encoded with the following values:
* _Call_: 1
* _Reply_: 2
* _Exception_: 3
* _Oneway_: 4
## Struct
A *Struct* is a sequence of zero or more fields, followed by a stop field. Each field starts with a field header and
is followed by the encoded field value. The encoding can be summarized by the following BNF:
```
struct ::= ( field-header field-value )* stop-field
field-header ::= field-type field-id
```
Because each field header contains the field-id (as defined by the Thrift IDL file), the fields can be encoded in any
order. Thrift's type system is not extensible; you can only encode the primitive types and structs. Therefore is also
possible to handle unknown fields while decoding; these are simply ignored. While decoding the field type can be used to
determine how to decode the field value.
Note that the field name is not encoded so field renames in the IDL do not affect forward and backward compatibility.
The default Java implementation (Apache Thrift 0.9.1) has undefined behavior when it tries to decode a field that has
another field-type then what is expected. Theoretically this could be detected at the cost of some additional checking.
Other implementation may perform this check and then either ignore the field, or return a protocol exception.
A *Union* is encoded exactly the same as a struct with the additional restriction that at most 1 field may be encoded.
An *Exception* is encoded exactly the same as a struct.
### Struct encoding
In the binary protocol field headers and the stop field are encoded as follows:
```
Binary protocol field header and field value:
+--------+--------+--------+--------+...+--------+
|tttttttt| field id | field value |
+--------+--------+--------+--------+...+--------+
Binary protocol stop field:
+--------+
|00000000|
+--------+
```
Where:
* `tttttttt` the field-type, a signed 8 bit integer.
* `field id` the field-id, a signed 16 bit integer in big endian order.
* `field-value` the encoded field value.
The following field-types are used:
* `BOOL`, encoded as `2`
* `BYTE`, encoded as `3`
* `DOUBLE`, encoded as `4`
* `I16`, encoded as `6`
* `I32`, encoded as `8`
* `I64`, encoded as `10`
* `STRING`, used for binary and string fields, encoded as `11`
* `STRUCT`, used for structs and union fields, encoded as `12`
* `MAP`, encoded as `13`
* `SET`, encoded as `14`
* `LIST`, encoded as `15`
## List and Set
List and sets are encoded the same: a header indicating the size and the element-type of the elements, followed by the
encoded elements.
```
Binary protocol list (5+ bytes) and elements:
+--------+--------+--------+--------+--------+--------+...+--------+
|tttttttt| size | elements |
+--------+--------+--------+--------+--------+--------+...+--------+
```
Where:
* `tttttttt` is the element-type, encoded as an int8
* `size` is the size, encoded as an int32, positive values only
* `elements` the element values
The element-type values are the same as field-types. The full list is included in the struct section above.
The maximum list/set size is configurable. By default there is no limit (meaning the limit is the maximum int32 value:
2147483647).
## Map
Maps are encoded with a header indicating the size, the element-type of the keys and the element-type of the elements,
followed by the encoded elements. The encoding follows this BNF:
```
map ::= key-element-type value-element-type size ( key value )*
```
```
Binary protocol map (6+ bytes) and key value pairs:
+--------+--------+--------+--------+--------+--------+--------+...+--------+
|kkkkkkkk|vvvvvvvv| size | key value pairs |
+--------+--------+--------+--------+--------+--------+--------+...+--------+
```
Where:
* `kkkkkkkk` is the key element-type, encoded as an int8
* `vvvvvvvv` is the value element-type, encoded as an int8
* `size` is the size of the map, encoded as an int32, positive values only
* `key value pairs` are the encoded keys and values
The element-type values are the same as field-types. The full list is included in the struct section above.
The maximum map size is configurable. By default there is no limit (meaning the limit is the maximum int32 value:
2147483647).
# BNF notation used in this document
The following BNF notation is used:
* a plus `+` appended to an item represents repetition; the item is repeated 1 or more times
* a star `*` appended to an item represents optional repetition; the item is repeated 0 or more times
* a pipe `|` between items represents choice, the first matching item is selected
* parenthesis `(` and `)` are used for grouping multiple items

294
vendor/git.apache.org/thrift.git/doc/specs/thrift-compact-protocol.md generated vendored Normal file
View file

@ -0,0 +1,294 @@
Thrift Compact protocol encoding
================================
<!--
--------------------------------------------------------------------
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
--------------------------------------------------------------------
-->
This documents describes the wire encoding for RPC using the Thrift *compact protocol*.
The information here is _mostly_ based on the Java implementation in the Apache thrift library (version 0.9.1) and
[THRIFT-110 A more compact format](https://issues.apache.org/jira/browse/THRIFT-110). Other implementation however,
should behave the same.
For background on Thrift see the [Thrift whitepaper (pdf)](https://thrift.apache.org/static/files/thrift-20070401.pdf).
# Contents
* Compact protocol
* Base types
* Message
* Struct
* List and Set
* Map
* BNF notation used in this document
# Compact protocol
## Base types
### Integer encoding
The _compact protocol_ uses multiple encodings for ints: the _zigzag int_, and the _var int_.
Values of type `int32` and `int64` are first transformed to a *zigzag int*. A zigzag int folds positive and negative
numbers into the positive number space. When we read 0, 1, 2, 3, 4 or 5 from the wire, this is translated to 0, -1, 1,
-2 or 2 respectively. Here are the (Scala) formulas to convert from int32/int64 to a zigzag int and back:
```scala
def intToZigZag(n: Int): Int = (n << 1) ^ (n >> 31)
def zigzagToInt(n: Int): Int = (n >>> 1) ^ - (n & 1)
def longToZigZag(n: Long): Long = (n << 1) ^ (n >> 63)
def zigzagToLong(n: Long): Long = (n >>> 1) ^ - (n & 1)
```
The zigzag int is then encoded as a *var int*. Var ints take 1 to 5 bytes (int32) or 1 to 10 bytes (int64). The most
significant bit of each byte indicates if more bytes follow. The concatenation of the least significant 7 bits from each
byte form the number, where the first byte has the most significant bits (so they are in big endian or network order).
Var ints are sometimes used directly inside the compact protocol to represent positive numbers.
To encode an `int16` as zigzag int, it is first converted to an `int32` and then encoded as such. The type `int8` simply
uses a single byte as in the binary protocol.
### Enum encoding
The generated code encodes `Enum`s by taking the ordinal value and then encoding that as an int32.
### Binary encoding
Binary is sent as follows:
```
Binary protocol, binary data, 1+ bytes:
+--------+...+--------+--------+...+--------+
| byte length | bytes |
+--------+...+--------+--------+...+--------+
```
Where:
* `byte length` is the length of the byte array, using var int encoding (must be >= 0).
* `bytes` are the bytes of the byte array.
### String encoding
*String*s are first encoded to UTF-8, and then send as binary.
### Double encoding
Values of type `double` are first converted to an int64 according to the IEEE 754 floating-point "double format" bit
layout. Most run-times provide a library to make this conversion. Both the binary protocol as the compact protocol then
encode the int64 in 8 bytes in big endian order.
### Boolean encoding
Booleans are encoded differently depending on whether it is a field value (in a struct) or an element value (in a set,
list or map). Field values are encoded directly in the field header. Element values of type `bool` are sent as an int8;
true as `1` and false as `0`.
## Message
A `Message` on the wire looks as follows:
```
Compact protocol Message (4+ bytes):
+--------+--------+--------+...+--------+--------+...+--------+--------+...+--------+
|pppppppp|mmmvvvvv| seq id | name length | name |
+--------+--------+--------+...+--------+--------+...+--------+--------+...+--------+
```
Where:
* `pppppppp` is the protocol id, fixed to `1000 0010`, 0x82.
* `mmm` is the message type, an unsigned 3 bit integer.
* `vvvvv` is the version, an unsigned 5 bit integer, fixed to `00001`.
* `seq id` is the sequence id, a signed 32 bit integer encoded as a var int.
* `name length` is the byte length of the name field, a signed 32 bit integer encoded as a var int (must be >= 0).
* `name` is the method name to invoke, a UTF-8 encoded string.
Message types are encoded with the following values:
* _Call_: 1
* _Reply_: 2
* _Exception_: 3
* _Oneway_: 4
### Struct
A *Struct* is a sequence of zero or more fields, followed by a stop field. Each field starts with a field header and
is followed by the encoded field value. The encoding can be summarized by the following BNF:
```
struct ::= ( field-header field-value )* stop-field
field-header ::= field-type field-id
```
Because each field header contains the field-id (as defined by the Thrift IDL file), the fields can be encoded in any
order. Thrift's type system is not extensible; you can only encode the primitive types and structs. Therefore is also
possible to handle unknown fields while decoding; these are simply ignored. While decoding the field type can be used to
determine how to decode the field value.
Note that the field name is not encoded so field renames in the IDL do not affect forward and backward compatibility.
The default Java implementation (Apache Thrift 0.9.1) has undefined behavior when it tries to decode a field that has
another field-type then what is expected. Theoretically this could be detected at the cost of some additional checking.
Other implementation may perform this check and then either ignore the field, or return a protocol exception.
A *Union* is encoded exactly the same as a struct with the additional restriction that at most 1 field may be encoded.
An *Exception* is encoded exactly the same as a struct.
### Struct encoding
```
Compact protocol field header (short form) and field value:
+--------+--------+...+--------+
|ddddtttt| field value |
+--------+--------+...+--------+
Compact protocol field header (1 to 3 bytes, long form) and field value:
+--------+--------+...+--------+--------+...+--------+
|0000tttt| field id | field value |
+--------+--------+...+--------+--------+...+--------+
Compact protocol stop field:
+--------+
|00000000|
+--------+
```
Where:
* `dddd` is the field id delta, an unsigned 4 bits integer, strictly positive.
* `tttt` is field-type id, an unsigned 4 bit integer.
* `field id` the field id, a signed 16 bit integer encoded as zigzag int.
* `field-value` the encoded field value.
The field id delta can be computed by `current-field-id - previous-field-id`, or just `current-field-id` if this is the
first of the struct. The short form should be used when the field id delta is in the range 1 - 15 (inclusive).
The following field-types can be encoded:
* `BOOLEAN_TRUE`, encoded as `1`
* `BOOLEAN_FALSE`, encoded as `2`
* `BYTE`, encoded as `3`
* `I16`, encoded as `4`
* `I32`, encoded as `5`
* `I64`, encoded as `6`
* `DOUBLE`, encoded as `7`
* `BINARY`, used for binary and string fields, encoded as `8`
* `LIST`, encoded as `9`
* `SET`, encoded as `10`
* `MAP`, encoded as `11`
* `STRUCT`, used for both structs and union fields, encoded as `12`
Note that because there are 2 specific field types for the boolean values, the encoding of a boolean field value has no
length (0 bytes).
## List and Set
List and sets are encoded the same: a header indicating the size and the element-type of the elements, followed by the
encoded elements.
```
Compact protocol list header (1 byte, short form) and elements:
+--------+--------+...+--------+
|sssstttt| elements |
+--------+--------+...+--------+
Compact protocol list header (2+ bytes, long form) and elements:
+--------+--------+...+--------+--------+...+--------+
|1111tttt| size | elements |
+--------+--------+...+--------+--------+...+--------+
```
Where:
* `ssss` is the size, 4 bit unsigned int, values `0` - `14`
* `tttt` is the element-type, a 4 bit unsigned int
* `size` is the size, a var int (int32), positive values `15` or higher
* `elements` are the encoded elements
The short form should be used when the length is in the range 0 - 14 (inclusive).
The following element-types are used (note that these are _different_ from the field-types):
* `BOOL`, encoded as `2`
* `BYTE`, encoded as `3`
* `DOUBLE`, encoded as `4`
* `I16`, encoded as `6`
* `I32`, encoded as `8`
* `I64`, encoded as `10`
* `STRING`, used for binary and string fields, encoded as `11`
* `STRUCT`, used for structs and union fields, encoded as `12`
* `MAP`, encoded as `13`
* `SET`, encoded as `14`
* `LIST`, encoded as `15`
The maximum list/set size is configurable. By default there is no limit (meaning the limit is the maximum int32 value:
2147483647).
## Map
Maps are encoded with a header indicating the size, the type of the keys and the element-type of the elements, followed
by the encoded elements. The encoding follows this BNF:
```
map ::= empty-map | non-empty-map
empty-map ::= `0`
non-empty-map ::= size key-element-type value-element-type (key value)+
```
```
Compact protocol map header (1 byte, empty map):
+--------+
|00000000|
+--------+
Compact protocol map header (2+ bytes, non empty map) and key value pairs:
+--------+...+--------+--------+--------+...+--------+
| size |kkkkvvvv| key value pairs |
+--------+...+--------+--------+--------+...+--------+
```
Where:
* `size` is the size, a var int (int32), strictly positive values
* `kkkk` is the key element-type, a 4 bit unsigned int
* `vvvv` is the value element-type, a 4 bit unsigned int
* `key value pairs` are the encoded keys and values
The element-types are the same as for lists. The full list is included in the 'List and set' section.
The maximum map size is configurable. By default there is no limit (meaning the limit is the maximum int32 value:
2147483647).
# BNF notation used in this document
The following BNF notation is used:
* a plus `+` appended to an item represents repetition; the item is repeated 1 or more times
* a star `*` appended to an item represents optional repetition; the item is repeated 0 or more times
* a pipe `|` between items represents choice, the first matching item is selected
* parenthesis `(` and `)` are used for grouping multiple items

101
vendor/git.apache.org/thrift.git/doc/specs/thrift-protocol-spec.md generated vendored Normal file
View file

@ -0,0 +1,101 @@
Thrift Protocol Structure
====================================================================
Last Modified: 2007-Jun-29
<!--
--------------------------------------------------------------------
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
--------------------------------------------------------------------
-->
This document describes the structure of the Thrift protocol
without specifying the encoding. Thus, the order of elements
could in some cases be rearranged depending upon the TProtocol
implementation, but this document specifies the minimum required
structure. There are some "dumb" terminals like STRING and INT
that take the place of an actual encoding specification.
They key point to notice is that ALL messages are just one wrapped
`<struct>`. Depending upon the message type, the `<struct>` can be
interpreted as the argument list to a function, the return value
of a function, or an exception.
--------------------------------------------------------------------
```
<message> ::= <message-begin> <struct> <message-end>
<message-begin> ::= <method-name> <message-type> <message-seqid>
<method-name> ::= STRING
<message-type> ::= T_CALL | T_REPLY | T_EXCEPTION | T_ONEWAY
<message-seqid> ::= I32
<struct> ::= <struct-begin> <field>* <field-stop> <struct-end>
<struct-begin> ::= <struct-name>
<struct-name> ::= STRING
<field-stop> ::= T_STOP
<field> ::= <field-begin> <field-data> <field-end>
<field-begin> ::= <field-name> <field-type> <field-id>
<field-name> ::= STRING
<field-type> ::= T_BOOL | T_BYTE | T_I8 | T_I16 | T_I32 | T_I64 | T_DOUBLE
| T_STRING | T_BINARY | T_STRUCT | T_MAP | T_SET | T_LIST
<field-id> ::= I16
<field-data> ::= I8 | I16 | I32 | I64 | DOUBLE | STRING | BINARY
<struct> | <map> | <list> | <set>
<map> ::= <map-begin> <field-datum>* <map-end>
<map-begin> ::= <map-key-type> <map-value-type> <map-size>
<map-key-type> ::= <field-type>
<map-value-type> ::= <field-type>
<map-size> ::= I32
<list> ::= <list-begin> <field-data>* <list-end>
<list-begin> ::= <list-elem-type> <list-size>
<list-elem-type> ::= <field-type>
<list-size> ::= I32
<set> ::= <set-begin> <field-data>* <set-end>
<set-begin> ::= <set-elem-type> <set-size>
<set-elem-type> ::= <field-type>
<set-size> ::= I32
```

178
vendor/git.apache.org/thrift.git/doc/specs/thrift-rpc.md generated vendored Normal file
View file

@ -0,0 +1,178 @@
Thrift Remote Procedure Call
============================
<!--
--------------------------------------------------------------------
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
--------------------------------------------------------------------
-->
This document describes the high level message exchange between the Thrift RPC client and server.
See [thrift-binary-protocol.md] and [thrift-compact-protocol.md] for a description of how the exchanges are encoded on
the wire.
In addition, this document compares the binary protocol with the compact protocol. Finally it describes the framed vs.
unframed transport.
The information here is _mostly_ based on the Java implementation in the Apache thrift library (version 0.9.1 and
0.9.3). Other implementation however, should behave the same.
For background on Thrift see the [Thrift whitepaper (pdf)](https://thrift.apache.org/static/files/thrift-20070401.pdf).
# Contents
* Thrift Message exchange for Remote Procedure Call
* Message
* Request struct
* Response struct
* Protocol considerations
* Comparing binary and compact protocol
* Compatibility
* Framed vs unframed transport
# Thrift Remote Procedure Call Message exchange
Both the binary protocol and the compact protocol assume a transport layer that exposes a bi-directional byte stream,
for example a TCP socket. Both use the following exchange:
1. Client sends a `Message` (type `Call` or `Oneway`). The TMessage contains some metadata and the name of the method
to invoke.
2. Client sends method arguments (a struct defined by the generate code).
3. Server sends a `Message` (type `Reply` or `Exception`) to start the response.
4. Server sends a struct containing the method result or exception.
The pattern is a simple half duplex protocol where the parties alternate in sending a `Message` followed by a struct.
What these are is described below.
Although the standard Apache Thrift Java clients do not support pipelining (sending multiple requests without waiting
for an response), the standard Apache Thrift Java servers do support it.
## Message
A *Message* contains:
* _Name_, a string (can be empty).
* _Message type_, a message types, one of `Call`, `Reply`, `Exception` and `Oneway`.
* _Sequence id_, a signed int32 integer.
The *sequence id* is a simple message id assigned by the client. The server will use the same sequence id in the
message of the response. The client uses this number to detect out of order responses. Each client has an int32 field
which is increased for each message. The sequence id simply wraps around when it overflows.
The *name* indicates the service method name to invoke. The server copies the name in the response message.
When the *multiplexed protocol* is used, the name contains the service name, a colon `:` and the method name. The
multiplexed protocol is not compatible with other protocols.
The *message type* indicates what kind of message is sent. Clients send requests with TMessages of type `Call` or
`Oneway` (step 1 in the protocol exchange). Servers send responses with messages of type `Exception` or `Reply` (step
3).
Type `Reply` is used when the service method completes normally. That is, it returns a value or it throws one of the
exceptions defined in the Thrift IDL file.
Type `Exception` is used for other exceptions. That is: when the service method throws an exception that is not declared
in the Thrift IDL file, or some other part of the Thrift stack throws an exception. For example when the server could
not encode or decode a message or struct.
In the Java implementation (0.9.3) there is different behavior for the synchronous and asynchronous server. In the async
server all exceptions are send as a `TApplicationException` (see 'Response struct' below). In the synchronous Java
implementation only (undeclared) exceptions that extend `TException` are send as a `TApplicationException`. Unchecked
exceptions lead to an immediate close of the connection.
Type `Oneway` is only used starting from Apache Thrift 0.9.3. Earlier versions do _not_ send TMessages of type `Oneway`,
even for service methods defined with the `oneway` modifier.
When client sends a request with type `Oneway`, the server must _not_ send a response (steps 3 and 4 are skipped). Note
that the Thrift IDL enforces a return type of `void` and does not allow exceptions for oneway services.
## Request struct
The struct that follows the message of type `Call` or `Oneway` contains the arguments of the service method. The
argument ids correspond to the field ids. The name of the struct is the name of the method with `_args` appended.
For methods without arguments an struct is sent without fields.
## Response struct
The struct that follows the message of type `Reply` are structs in which exactly 1 of the following fields is encoded:
* A field with name `success` and id `0`, used in case the method completed normally.
* An exception field, name and id are as defined in the `throws` clause in the Thrift IDL's service method definition.
When the message is of type `Exception` the struct is encoded as if it was declared by the following IDL:
```
exception TApplicationException {
1: string message,
2: i32 type
}
```
The following exception types are defined in the java implementation (0.9.3):
* _unknown_: 0, used in case the type from the peer is unknown.
* _unknown method_: 1, used in case the method requested by the client is unknown by the server.
* _invalid message type_: 2, no usage was found.
* _wrong method name_: 3, no usage was found.
* _bad sequence id_: 4, used internally by the client to indicate a wrong sequence id in the response.
* _missing result_: 5, used internally by the client to indicate a response without any field (result nor exception).
* _internal error_: 6, used when the server throws an exception that is not declared in the Thrift IDL file.
* _protocol error_: 7, used when something goes wrong during decoding. For example when a list is too long or a required
field is missing.
* _invalid transform_: 8, no usage was found.
* _invalid protocol_: 9, no usage was found.
* _unsupported client type_: 10, no usage was found.
# Protocol considerations
## Comparing binary and compact protocol
The binary protocol is fairly simple and therefore easy to process. The compact protocol needs less bytes to send the
same data at the cost of additional processing. As bandwidth is usually the bottleneck, the compact protocol is almost
always slightly faster.
## Compatibility
A server could automatically determine whether a client talks the binary protocol or the compact protocol by
investigating the first byte. If the value is `1000 0001` or `0000 0000` (assuming a name shorter then ±16 MB) it is the
binary protocol. When the value is `1000 0010` it is talking the compact protocol.
## Framed vs. unframed transport
The first thrift binary wire format was unframed. This means that information is sent out in a single stream of bytes.
With unframed transport the (generated) processors will read directly from the socket (though Apache Thrift does try to
grab all available bytes from the socket in a buffer when it can).
Later, Thrift introduced the framed transport.
With framed transport the full request and response (the TMessage and the following struct) are first written to a
buffer. Then when the struct is complete (transport method `flush` is hijacked for this), the length of the buffer is
written to the socket first, followed by the buffered bytes. The combination is called a _frame_. On the receiver side
the complete frame is first read in a buffer before the message is passed to a processor.
The length prefix is a 4 byte signed int, send in network (big endian) order.
The following must be true: `0` <= length <= `16384000` (16M).
Framed transport was introduced to ease the implementation of async processors. An async processor is only invoked when
all data is received. Unfortunately, framed transport is not ideal for large messages as the entire frame stays in
memory until the message has been processed. In addition, the java implementation merges the incoming data to a single,
growing byte array. Every time the byte array is full it needs to be copied to a new larger byte array.
Framed and unframed transports are not compatible with each other.

108
vendor/git.apache.org/thrift.git/doc/specs/thrift-sasl-spec.txt generated vendored Normal file
View file

@ -0,0 +1,108 @@
A Thrift SASL message shall be a byte array of the following form:
| 1-byte status code | 4-byte payload length | variable-length payload |
The length fields shall be interpreted as integers, with the high byte sent
first. This indicates the length of the field immediately following it, not
including the status code or the length bytes.
The possible status codes are:
0x01 - START - Hello, let's go on a date.
0x02 - OK - Everything's been going alright so far, let's see each other again.
0x03 - BAD - I understand what you're saying. I really do. I just don't like it. We have to break up.
0x04 - ERROR - We can't go on like this. It's like you're speaking another language.
0x05 - COMPLETE - Will you marry me?
The Thrift SASL communication will proceed as follows:
1. The client is configured at instantiation of the transport with a single
underlying SASL security mechanism that it supports.
2. The server is configured with a mapping of underlying security mechanism
name -> mechanism options.
3. At connection time, the client will initiate communication by sending the
server a START message. The payload of this message will be the name of the
underlying security mechanism that the client would like to use.
This mechanism name shall be 1-20 characters in length, and follow the
specifications for SASL mechanism names specified in RFC 2222.
4. The server receives this message and, if the mechanism name provided is
among the set of mechanisms this server transport is configured to accept,
appropriate initialization of the underlying security mechanism may take place.
If the mechanism name is not one which the server is configured to support, the
server shall return the BAD byte, followed by a 4-byte, potentially zero-value
message length, followed by the potentially zero-length payload which may be a
status code or message indicating failure. No further communication may take
place via this transport. If the mechanism name is one which the server
supports, then proceed to step 5.
5. Following the START message, the client must send another message containing
the "initial response" of the chosen SASL implementation. The client may send
this message piggy-backed on the "START" message of step 3. The message type
of this message must be either "OK" or "COMPLETE", depending on whether the
SASL implementation indicates that this side of the authentication has been
satisfied.
6. The server then provides the byte array of the payload received to its
underlying security mechanism. A challenge is generated by the underlying
security mechanism on the server, and this is used as the payload for a message
sent to the client. This message shall consist of an OK byte, followed by the
non-zero message length word, followed by the payload.
7. The client receives this message from the server and passes the payload to
its underlying security mechanism to generate a response. The client then sends
the server an OK byte, followed by the non-zero-value length of the response,
followed by the bytes of the response as the payload.
8. Steps 6 and 7 are repeated until both security mechanisms are satisfied with
the challenge/response exchange. When either side has completed its security
protocol, its next message shall be the COMPLETE byte, followed by a 4-byte
potentially zero-value length word, followed by a potentially zero-length
payload. This payload will be empty except for those underlying security
mechanisms which provide additional data with success.
If at any point in time either side is able to interpret the challenge or
response sent by the other, but is dissatisfied with the contents thereof, this
side should send the other a BAD byte, followed by a 4-byte potentially
zero-value length word, followed by an optional, potentially zero-length
message encoded in UTF-8 indicating failure. This message should be passed to
the protocol above the thrift transport by whatever mechanism is appropriate
and idiomatic for the particular language these thrift bindings are for.
If at any point in time either side fails to interpret the challenge or
response sent by the other, this side should send the other an ERROR byte,
followed by a 4-byte potentially zero-value length word, followed by an
optional, potentially zero-length message encoded in UTF-8. This message should
be passed to the protocol above the thrift transport by whatever mechanism is
appropriate and idiomatic for the particular language these thrift bindings are
for.
If step 8 completes successfully, then the communication is considered
authenticated and subsequent communication may commence.
If step 8 fails to complete successfully, then no further communication may
take place via this transport.
8. All writes to the underlying transport must be prefixed by the 4-byte length
of the payload data, followed by the payload. All reads from this transport
should read the 4-byte length word, then read the full quantity of bytes
specified by this length word.
If no SASL QOP (quality of protection) is negotiated during steps 6 and 7, then
all subsequent writes to/reads from this transport are written/read unaltered,
save for the length prefix, to the underlying transport.
If a SASL QOP is negotiated, then this must be used by the Thrift transport for
all subsequent communication. This is done by wrapping subsequent writes to the
transport using the underlying security mechanism, and unwrapping subsequent
reads from the underlying transport. Note that in this case, the length prefix
of the write to the underlying transport is the length of the data after it has
been wrapped by the underlying security mechanism. Note that the complete
message must be read before giving this data to the underlying security
mechanism for unwrapping.
If at any point in time reading of a message fails either because of a
malformed length word or failure to unwrap by the underlying security
mechanism, then all further communication on this transport must cease.

1057
vendor/git.apache.org/thrift.git/doc/specs/thrift.tex generated vendored Normal file
View file

File diff suppressed because it is too large Load diff