Merge pull request #288 from qzhuyan/prepare-v0.1.0

docs: prepare for 0.1.0

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

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

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

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