From 651e2c02d657bc562c0473a15233c30275da1e88 Mon Sep 17 00:00:00 2001 From: William Yang Date: Tue, 28 May 2024 15:51:51 +0200 Subject: [PATCH] docs: prepare for 0.1.0 --- README.md | 136 ++++++++++++++++++++++---------------- docs/messages_to_owner.md | 2 +- docs/todo.org | 27 -------- src/quicer.erl | 8 ++- 4 files changed, 88 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 2da5fa41..e08e2df4 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,32 @@ -# quicer +# Quicer -QUIC protocol erlang library. +QUIC (Next-generation transport protocol) erlang library. [msquic](https://github.com/microsoft/msquic) NIF binding. -Project Status: WIP (actively), POC quality - -API: is not stable, might be changed in the future. +Project Status: Preview ![Erlang](https://img.shields.io/badge/Erlang-white.svg?style=plastic&logo=erlang&logoColor=a90533) ![CI](https://github.com/emqx/quic/workflows/ci/badge.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Coverage Status](https://coveralls.io/repos/emqx/quic/badge.png?branch=main)](https://coveralls.io/r/emqx/quic?branch=main) -# OS Support -| OS | Status | -|---------|-----------| -| Linux | Supported | -| macOS | Supported | -| Windows | TBD | - -# BUILD - -## Dependencies - -1. OTP22+ -1. rebar3 -1. cmake3.16+ -1. [CLOG](https://github.com/microsoft/CLOG) (required for debug logging only) -1. LTTNG2.12 (required for debug build only) - -## With DEBUG - -Debug build dependency: [CLOG](https://github.com/microsoft/CLOG) - -``` sh -$ rebar3 compile -# OR -$ make -``` - -note, - -To enable logging and release build: +## OS Support -``` sh -export CMAKE_BUILD_TYPE=Debug -export QUIC_ENABLE_LOGGING=ON -export QUICER_USE_LTTNG=1 -make -``` +| OS | Status | +|---------|-------------| +| Linux | Supported | +| macOS | Supported | +| Windows | Help Needed | -## BUILD with logging to stdout +# Add to your project -``` sh -QUIC_LOGGING_TYPE=stdout make -``` - -## Without DEBUG +## rebar.config -``` sh -export CMAKE_BUILD_TYPE=Release -make +``` erlang +{deps, [ + {quicer, {git, "https://github.com/qzhuyan/quic.git", {tag, "0.1.0"}}}, + ... ``` # Examples @@ -99,23 +64,82 @@ receive {quic, <<"pong">>, Stm, _Props} -> ok end, ok = quicer:close_connection(Conn). ``` +## Try connect to Google with QUIC transport -# TEST - -``` sh -$ make test +``` erlang +%% Connect to google and disconnect, +%% You could also tweak the parameters to see how it goes +{ok, Conn} = quicer:connect("google.com", 443, [{alpn, ["h3"]}, + {verify, verify_peer}, + {peer_unidi_stream_count, 3}], 5000), +quicer:shutdown_connection(Conn). ``` +## More examples in test dir + +refer to [test](./test) dir. + # Documentation +## Get Started + +1. Understand the `handles` and the `ownership` in [Terminology](docs/Terminology.md) + +1. Then check how to receives the data and signals: [Messages](docs/messages_to_owner.md) + +1. Read more in [msquic doc](https://github.com/microsoft/msquic/tree/main/docs) + +## Offline hex doc + ``` sh $ make doc +$ firefox doc/index.html ``` -Then check the doc in browser: +# Dependencies +1. OTP25+ +1. rebar3 +1. cmake3.16+ + +# Build and test + +## Dev mode ``` sh -$ firefox doc/index.html +$ make ci +``` + +# Troubleshooting + +### Log to `stdout` + +Debug log could be enabled to print to `stdout` with the envvar `QUIC_LOGGING_TYPE=stdout` + +``` sh +QUIC_LOGGING_TYPE=stdout make +``` + +``` sh +%% Debug one testcase +QUIC_LOGGING_TYPE=stdout rebar3 ct --suite test/quicer_connection_SUITE.erl --case tc_conn_basic_verify_peer +``` + +### Decrypt traffic with Wireshark + +Client could specify the connect param `sslkeylogfile` to record tls secrets for wireshark to decrypt. + +``` erlang + {ok, Conn} = quicer:connect( + "google.com", + 443, + [ + {verify, verify_peer}, + {sslkeylogfile, "/tmp/SSLKEYLOGFILE"}, + {peer_unidi_stream_count, 3}, + {alpn, ["h3"]} + ], + 5000 + ) ``` # License diff --git a/docs/messages_to_owner.md b/docs/messages_to_owner.md index 5e52c4d6..87be3987 100644 --- a/docs/messages_to_owner.md +++ b/docs/messages_to_owner.md @@ -338,7 +338,7 @@ Connection is resumed with binary session data or with 'false' means empty sessi ### New Session Ticket -**Client Only** The client received the `NST`` (new session ticket) from the server if `QUICER_CONNECTION_EVENT_MASK_NST` had been +**Client Only** The client received the `NST` (new session ticket) from the server if `QUICER_CONNECTION_EVENT_MASK_NST` had been set in connection opt `quic_event_mask` when client starts the connection. ``` erlang diff --git a/docs/todo.org b/docs/todo.org index 79d11327..2dd66cdf 100644 --- a/docs/todo.org +++ b/docs/todo.org @@ -6,21 +6,11 @@ Feature todo list, priority descending -** Stream behavior should able to handle multiple streams -One process could become the owner of multiple streams in the scenario -that these streams are correlated. - ** Impl ConfigurationLoadCredential Load QUIC_CREDENTIAL_CONFIG to configuration ** Check shutdown connection wait for peer to close or not -** Get/Set Context -with lock protection set/get the callback context. - -** New API: open_send(connection_handle(), Data, Flags) -Open stream over this connection and send without starting the stream - ** Unintentional Transport Migration ** NIF Segfault recover @@ -40,24 +30,7 @@ Open stream over this connection and send without starting the stream - Use imm handle Maybe very less performance gain but still worth to change it. -- 0-RTT NST - - stateful and stateless. - - make sending NST configurable - check types. -- Level of APIs - - Current API are designd to easily migrate from TCP. - - QUIC can provide more detailed error info that a simple {error, Info} cannot hold. - - QUIC can provide more flags while doing any calls - - So we may need different levels of APIs. - Level 1: Simple and for ease of migration from TCP/TLS - Level 2: Expose details but with some common generic behaviors - Level 3: Pure NIF calls, application caller manages everything but also means - Quicer must be more transparent diff --git a/src/quicer.erl b/src/quicer.erl index 5e489d11..ef126f81 100644 --- a/src/quicer.erl +++ b/src/quicer.erl @@ -863,7 +863,7 @@ shutdown_stream(Stream, Timeout) -> %% %% Flags could be used to control the behavior like half-close. %% @end -%% @see async_shutdown_stream/4 +%% @see async_shutdown_stream/3 -spec shutdown_stream( stream_handle(), stream_shutdown_flags(), @@ -1131,14 +1131,20 @@ handoff_stream(Stream, NewOwner) -> handoff_stream(Stream, NewOwner, undefined). %% @doc Used by Old stream owner to handoff to the new stream owner. +%% %% 1. The Stream will be put into passive mode so the data is paused. +%% %% 2. The Stream signal buffer will be enabled, so the signal is paused. +%% %% 3. Stream messages (for both data and sig )in the current owners process messages queue will %% be forwarded to the New Owner's mailbox in the same recv order. +%% %% 4. Set the control process of the stream to the new owner, signal buffer will be flushed to new owner if succeed, otherwise to the old owner +%% %% 5. A signal msg `{handoff_done, Stream, PostHandoff}' will be sent to the new owner. %% The new owner should block for this message before handle any stream data to %% ensure the ordering. +%% %% 6. Revert stream active mode whatever handoff fail or success. %% also @see wait_for_handoff/2 %% also @see controlling_process/2