Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: prepare for 0.1.0 #288

Merged
merged 1 commit into from
May 31, 2024
Merged

docs: prepare for 0.1.0 #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 80 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/messages_to_owner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 0 additions & 27 deletions docs/todo.org
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
8 changes: 7 additions & 1 deletion src/quicer.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Expand Down Expand Up @@ -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
Expand Down
Loading