LSQUIC Client: Initial release

CMakeLists.txt

@@ -0,0 +1,89 @@
+# Copyright (c) 2017 LiteSpeed Technologies Inc.  See LICENSE.
+cmake_minimum_required(VERSION 2.8)
+
+
+project(lsquic)
+
+# We prefer clang
+IF(NOT ("${CMAKE_C_COMPILER}" MATCHES "ccc-analyzer" OR
+        "${CMAKE_C_COMPILER}" MATCHES "gcc"          OR
+        "${CMAKE_C_COMPILER}" MATCHES "afl-gcc"))
+    FIND_PROGRAM(CLANG "clang")
+    IF(CLANG)
+        SET(CMAKE_C_COMPILER "${CLANG}")
+    ENDIF()
+ENDIF()
+
+# By default, we compile in development mode.  To compile production code,
+# pass -DDEVEL_MODE=0 to cmake (before that, `make clean' and remove any
+# cmake cache files).
+#
+IF(NOT DEFINED DEVEL_MODE)
+    SET(DEVEL_MODE 1)
+ENDIF()
+
+
+MESSAGE(STATUS "DEVEL_MODE: ${DEVEL_MODE}")
+
+SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -Wall -Wextra -Wno-unused-parameter")
+SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -fno-omit-frame-pointer")
+
+IF(CMAKE_COMPILER_IS_GNUCC AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 4.9)
+    SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -Wno-missing-field-initializers")
+ENDIF()
+IF(DEVEL_MODE EQUAL 1)
+    SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -O0 -g3")
+    # -Werror is used to force us to fix warnings early.
+    SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -Werror")
+    IF(CMAKE_C_COMPILER MATCHES "clang")
+        SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -fsanitize=address")
+    ENDIF()
+    # Uncomment to enable fault injection testing via libfiu:
+    #SET (MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -DFIU_ENABLE=1")
+    #SET (FIULIB "fiu")
+ELSE()
+    SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -O3 -g0")
+    SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -DNDEBUG")
+    # Comment out the following line to compile out debug messages:
+    #SET(MY_CMAKE_FLAGS "${MY_CMAKE_FLAGS} -DLSQUIC_LOWEST_LOG_LEVEL=LSQ_LOG_INFO")
+ENDIF()
+
+IF(MY_CMAKE_FLAGS MATCHES "fsanitize=address")
+    MESSAGE(STATUS "AddressSanitizer is ON")
+ELSE()
+    MESSAGE(STATUS "AddressSanitizer is OFF")
+ENDIF()
+
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS}  ${MY_CMAKE_FLAGS} $ENV{EXTRA_CFLAGS}")
+
+MESSAGE(STATUS "Compiler flags: ${CMAKE_C_FLAGS}")
+
+
+SET(CMAKE_INCLUDE_CURRENT_DIR ON)
+include_directories( include )
+include_directories( ${BORINGSSL_INCLUDE} )
+
+link_directories( ${BORINGSSL_LIB} )
+
+IF(${CMAKE_SYSTEM_NAME} MATCHES "FreeBSD")
+    # Find libevent on FreeBSD:
+    include_directories( /usr/local/include )
+    link_directories( /usr/local/lib )
+ENDIF()
+
+add_executable(http_client test/http_client.c test/prog.c test/test_common.c test/test_cert.c)
+
+target_link_libraries(http_client lsquic event pthread libssl.a libcrypto.a libdecrepit.a ${FIULIB} z m)
+
+add_subdirectory(src)
+
+IF(DEVEL_MODE EQUAL 1)
+    # Our test framework relies on assertions, only compile if assertions are
+    # enabled.
+    #
+    add_subdirectory(test)
+    enable_testing()
+ENDIF()
+
+
+ADD_CUSTOM_TARGET(docs doxygen dox.cfg)

EXAMPLES.txt

@@ -0,0 +1,134 @@
+# Copyright (c) 2017 LiteSpeed Technologies Inc.  See LICENSE.
+LSQUIC Examples
+===============
+
+test/http_client.c demonstrates how to use HTTP features of QUIC.
+
+Usage Examples
+--------------
+
+Fetch Google's home page:
+
+    ./http_client -H www.google.com -s 74.125.22.106:443 -p /
+
+In the example above, -H specifies the domain; it is also used as the value
+of SNI paramater in the handshake.
+
+POST a file to calculate its CRC32 checksum:
+
+    ./http_client -H www.litespeedtech.com -s 127.0.0.1:443 \
+                        -p /cgi-bin/crc32.cgi -P file-256M -M POST
+
+    HTTP/1.1 200 OK
+    content-type: text/plain
+    date: Fri, 09 Jun 2017 08:40:45 GMT
+    server: LiteSpeed
+    alt-svc: quic=":443"; v="35,37"
+
+    CRC32: 2A0E7DBB
+
+This is a good way to check that the payload gets to the other side
+correctly.  The CGI script is:
+
+    #!/usr/bin/perl
+    use String::CRC32;
+    printf "Content-type: text/plain\r\n\r\nCRC32: %X\n", crc32(*STDIN)
+
+On the command line, I do
+
+    alias crc32="perl -MString::CRC32 -e'printf qq(%X\n), crc32(<>)'"
+
+To submit several requests concurrently, one can use -n and -r options:
+
+    ./http_client -H www.litespeedtech.com -s 127.0.0.1:443 \
+                -p /cgi-bin/crc32.cgi -P file-256M -M POST -n 3 -r 10
+
+This will open three parallel connections which will make ten POST
+requests together.
+
+To perform load testing, it is good to mix sending and receiving data:
+
+    for i in {1..100}; do
+        ./http_client $COMMON_OPTS -p /cgi-bin/crc32.cgi -P file-256M \
+                                                    -M POST >out-post.$i &
+        ./http_client $COMMON_OPTS -p /docs/file-256M >out-get.$i        &
+        sleep 1
+    done
+
+If you don't want to create a hundred 256-megabyte out-get.* files, use -K
+flag to discard output.
+
+Control QUIC Settings via -o Flag
+---------------------------------
+
+Most of the settings in struct lsquic_engine_settings can be controlled
+via -o flag.  With exception of es_versions, which is a bit mask, other
+es_* options can be mapped to corresponding -o value via s/^es_//:
+
+    es_cfcw             =>  -o cwcf=12345
+    es_max_streams_in   =>  -o max_streams_in=123
+
+And so on.
+
+The code to set options via -o flag lives in set_engine_option().  It is good
+to update this function at the same time as member fields are added to struct
+lsquic_engine_settings.
+
+Control LSQUIC Behavior via Environment Variables
+-------------------------------------------------
+
+LSQUIC_CUBIC_SHIFT_EPOCH
+
+    This environment variable determines whether cubic epoch is shifted
+    when sender is application-limited.
+
+    This is a leftover from the time when application-limited behavior was
+    implemented and is only available in debug builds.  By default, the
+    epoch is shifted.
+
+LSQUIC_PACER_INTERTICK
+
+    Number of microsecods to use as constant intertick time in lieu of the
+    pacer's dynamic intertick time approximation.
+
+    Only available in debug builds.
+
+Control Network-Related Stuff
+-----------------------------
+
+   -D          Set `do not fragment' flag on outgoing UDP packets.
+
+   -z BYTES    Maximum size of outgoing UDP packets.  The default is 1370
+               bytes for IPv4 socket and 1350 bytes for IPv6 socket.
+
+   -S opt=val  Socket options.  Supported options:
+                   sndbuf=12345    # Sets SO_SNDBUF
+                   rcvbuf=12345    # Sets SO_RCVBUF
+
+More Compilation Options
+------------------------
+
+-DFULL_CONN_STATS=1
+
+    Track some statistics about full connection -- packets in, sent, delayed,
+    stream payload per packet size ratio, and some others -- and print them
+    at NOTICE level when connection is destroyed.
+
+    This is useful when performing network testing and especially analyzing
+    the effects of changing send buffer size (see -S sndbuf= in the previous
+    section).
+
+-DLSQUIC_PACKINTS_SANITY_CHECK=1
+
+    Turn on sanity checking for packet interval code.  The packet interval
+    code, shared by both send and receive history modules, contained a bug
+    which prompted me to add a checking function.
+
+-DLSQUIC_SEND_STATS=0
+
+    Turn off statistics collection performed by the send controller: number
+    of packets sent, resent, and delayed.
+
+-DLSQUIC_LOWEST_LOG_LEVEL=LSQ_LOG_WARN
+
+    If you want to go even faster: compile out some log levels entirely.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 LiteSpeed Technologies Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software 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.

LICENSE.chrome

@@ -0,0 +1,32 @@
+A few parts of LiteSpeed QUIC library are based on proto-quic.  That
+code is covered by this additional license:
+
+------------------------------
+
+Copyright 2015 The Chromium Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+* Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,40 @@
+LiteSpeed QUIC (LSQUIC) Client Library README
+=============================================
+
+Description
+-----------
+
+LiteSpeed QUIC (LSQUIC) Client Library is an open-source implementation
+of QUIC functionality for clients.  It is released in the hope to speed
+the adoption of QUIC.  Most of the code in this distribution is used in
+our own products: LiteSpeed Web Server and ADC.  We think it is free of
+major problems.  Nevertheless, do not hesitate to report bugs back to us.
+Even better, send us fixes and improvements!
+
+Currently supported QUIC versions are Q035, Q037, Q038, Q039, and Q040.
+Support for newer versions will be added soon after they are released.
+The version(s) specified by IETF QUIC WG will be added once the IETF
+version of the protocol settles down a little.
+
+Documentation
+-------------
+
+The documentation for this module is admittedly sparse.  The API is
+documented in include/lsquic.h.  If you have doxygen, you can run
+`doxygen dox.cfg' or `make docs'.  The example program is
+test/http_client.c: a bare-bones, but working, QUIC client.  Have a look
+in EXAMPLES.txt to see how it can be used.
+
+Building
+--------
+
+To build LSQUIC, you need CMake and BoringSSL.  The example program
+uses libevent to provide the event loop.  In short:
+
+  cmake -DBORINGSSL_INCLUDE=/some/dir -DBORINGSSL_LIB=/some/other/dir .
+
+Have fun,
+
+LiteSpeed QUIC Team.
+
+Copyright (c) 2017 LiteSpeed Technologies Inc