Skip to content

Commit

Permalink
improve TcpServer documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@alec1o
alec1o committed Sep 9, 2023
1 parent f582586 commit 51222e7
Showing 1 changed file with 136 additions and 156 deletions.
292 changes: 136 additions & 156 deletions docs/tcp-server.md
View file
Original file line number Diff line number Diff line change
@@ -1,179 +1,160 @@
# TcpServer
``TcpServer`` is a ``class`` from the ``netly library`` that facilitates and simplifies the use of a ``tcp`` connection as a server
# <return>class</return> TcpServer

## Construtors
- Default
```cs
TcpServer server = new TcpServer(framing: true);
```
- Framing
```txt
Framing:
Enable or disable netly message framing
True:
Netly will use its own message framing protocol
False:
you will receive raw stream data without framing middleware.
For receive raw data use "TcpServer.OnData(Action<TcpClient, byte[]> callback)" or
TcpServer.OnEnter((TcpClient client) =>
{
client.OnData((data) => { /* do something here */ }));
});
```
###### Tcp server implementation

## Namespace
```cs
using Netly;
```

<br>

## Constructors
- ##### <return>TcpServer</return> TcpServer(<params>bool framing</params>)
- ``framing`` "enable or disable ``Stream protocol message framing``
- ``true`` Netly will use its own message framing protocol
- ``false`` You will receive raw stream data without framing middleware. For receive raw data use <params>TcpServer.OnData(Action<TcpClient, byte[]> callback)</params>

<br>

## Properties
- IsOpened ``bool`` <br>
<sub>Return true when the server socket is connected (bind port and listen clients) and false if not.</sub>
- ##### <return>bool</return> IsOpened
<sub>Return ``true`` when the server socket is connected (bind port and listen clients) and ``false`` if not.

- Host ``Netly.Core.Host`` <br>
<sub>It is an object that helps to care for and share a host's credentials.</sub>
</sub>

- Framing ``bool`` <br>
<sub>Return true when the instance is using ``MessageFraming protocol`` connection and false when the connection is not using ``MessageFraming protocol``</sub>
<br>

- IsEncrypted ``bool`` <br>
<sub>Return true when the instance is using ``TLS/SSL`` and false when isn't using this.</sub>
- ##### <return>Host</return> Host
<sub>``Host class`` is endpoint container, and contain (ip address, port, ip type), it's endpoint metadata.</sub>

## Methods (Trigger)
- Open ``void(Host host, int backlog)`` <br>
<sub>Used for open connection with server</sub>
```cs
Host host = new Host("127.0.0.1", 8080);
TcpServer.Open(host, 10);
```
- Close ``void()`` <br>
<sub>Used for close connection with server</sub>
```cs
TcpServer.Close();
```
- ToData ``void(byte[] buffer)`` ``void(string buffer)`` <br>
<sub>Used for send buffer (data) for all connected client</sub>
```cs
string stringBuffer = "Broadcast: Hello world!";
TcpServer.ToData(stringBuffer);
<br>

byte[] bytesBuffer = NE.GetBytes("Broadcast: Hello world!");
TcpServer.ToData(bytesBuffer);
```
- ToEvent ``void(string name, byte[] buffer)`` ``void(string name, string buffer)`` <br>
<sub>Used for send event for all connected client using NETLY_EVENT_PROTOCOL</sub>
```cs
string stringBuffer = "Hello world!";
TcpServer.ToEvent("broadcast-ping-from-string", stringBuffer);
- ##### <return>bool</return> Framing
<sub>Return ``true`` when the instance is using ``Netly MessageFraming protocol`` and ``false`` when the instance is not using ``MessageFraming protocol``</sub>

byte[] bytesBuffer = NE.GetBytes("Hello world!");
TcpServer.ToEvent("broadcast-ping-from-bytes", bytesBuffer);
```
- UseEncryption ``void(byte[] pfxCertificate, string pfxPassword, SslProtocols encryptionProtocol)`` <br>
<sub>Used for enable TLS/SSL from server side</sub>
```cs
// Warning: See about generate pfx on SSL/TLS page now we will see about startup this!
// Warning: Convert pfx file for bytes only using ASCII or UTF8
byte[] pfx = MyClass.GetPfxAsBytes();
string pfxPassword = MyClass.GetPfxPasswordFromEnvVars() ?? "my-secret-pfx-password"
<br>

// Enable SSL/TLS
TcpServer.UseEncryption(pfx, pfxPassword, SslProtocols.Tls12);
```
- ##### <return>bool</return> IsEncrypted
<sub>Return ``true`` when the instance is using ``TLS/SSL`` and ``false`` when isn't using this.</sub>

<br>

- ##### <return>TcpClient[]</return> Clients
<sub>Return array of all connected client (``TcpClient``)</sub>

## Methods (Callback)
- OnOpen ``void(Action callback)`` <br>
<sub>Invoke ``callback`` when connection opened</sub>
```cs
TcpServer.OnOpen(() =>
{
print("😅 Alecio is funny");
});
```
- OnClose ``void(Action callback)`` <br>
<sub>Invoke ``callback`` when connection closed</sub>
```cs
TcpServer.OnClose(() =>
{
print("😅 Alecio is funny");
});
```
- OnError ``void(Action<Exception> callback)`` <br>
<sub>Invoke ``callback``when the instance receives a internal error on opening connection or when receive invalid buffer (when MessageFraming are enabled)</sub>
```cs
TcpServer.OnError((Exception e) =>
{
print("😅 Alecio is funny");
});
```
- OnData ``void(Action<TcpClient, byte[]> callback)`` <br>
<sub>Invoke ``callback``when receive a buffer (data)</sub>
```cs
TcpServer.OnData((TcpClient client, byte[] data) =>
{
client.ToData(data); // echo: re-send received message
});
```
- OnEvent ``void(Action<TcpClient, string, byte[]> callback)`` <br>
<sub>Invoke ``callback`` when receive a event (NETLY_EVENT_PROTOCOL)</sub>
```cs
TcpServer.OnEvent((TcpClient client, string name, byte[] data) =>
{
if(name == "hello")
{
client.ToEvent("hello-callback", "😅 Alecio is funny");
}
else
{
client.ToEvent("non-hello", "😅 Netly is fast");
}
});
```
- OnModify ``void(Action<Socket> callback)`` <br>
<sub>Invoke ``callback`` when mouting socket instance for custom socket config (before open connection)</sub>
```cs
TcpServer.OnModify((Socket socket) =>
{
socket.NoDelay = true;
print("😅 Alecio is funny");
});
```
- OnEnter ``void(TcpClient client)`` <br>
<sub>called when client connected on server</sub>
```cs
TcpServer.OnEnter((TcpClient client) =>
{
print($"client connected from {client.Host}");

MyClass.AddClient(client, client.UUID);
<br>

// alternative of TcpServer.OnData((client, data) => { ... })
client.OnData((byte[] data) =>
{
client.OnData(data); // resend data for client (echo)
});
## Methods
> Triggers
// alternative of TcpServer.OnEvent((client, name, data) => { ... })
client.OnEvent((string name, byte[] data) =>
{
client.ToEvent(name, data); // resend event for client (echo)
});
- ##### <return>void</return> Open(<params>Host host</params>)
<sub>Open connection (bind and listen client), if connection not be open will call and expose exception on ``OnError`` callback.</sub>
- <sub>``Host`` Netly host instance (endpoint metadata)<sub/>

<br>

- ##### <return>void</return> Close()
<sub>Close connection (stop receive client buffer), if you need close connection use this method.</sub>

<br>

- ##### <return>void</return> ToData(<params>byte[] buffer</params>) <br> <return>void</return> ToData(<params>string buffer</params>)
<sub>Broadcast raw buffer to all connected clients from <params>Clients</params> array, ``buffer`` is ``string`` or ``byte[]`` (bytes).</sub>

<br>

- ##### <return>void</return> ToEvent(<params>string name</params>, <params>byte[] buffer</params>) <br> <return>void</return> ToEvent(<params>string name</params>, <params>string buffer</params>)
<sub>Broadcast event (netly-event) to all connected clients from <params>Clients</params> array, ``name`` is event identifier, ``buffer`` is event buffer (data), buffer is ``string`` or ``byte[]`` (bytes), if send buffer as string, netly will use ``NE.Default`` as encoding protocol.</sub>

<br>

> Callbacks
// alternative of TcpServer.OnExit((client) => { ... })
- ##### <return>void</return> OnOpen(<params>Action callback</params>)
<sub>Event responsible for receiving the connection opening information successfully</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>

<br>


- ##### <return>void</return> OnError(<params>Action&lt;Exception&gt; callback</params>)
<sub>Event responsible for receiving an error when opening a connection, the ``Exception`` contains the error information.</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>

<br>


- ##### <return>void</return> OnClose(<params>Action callback</params>)
<sub>Called when server close connection</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>

<br>


- ##### <return>void</return> OnEnter(<params>Action&lt;TcpClient&gt; callback</params>)
<sub>This event is responsible for receive client when connected</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>

<br>

- ##### <return>void</return> OnExit(<params>Action&lt;TcpClient&gt; callback</params>)
<sub>This event is responsible for detect when a client be disconnected</sub></sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>
- <return>Wrapper</return>
```cs
TcpServer.OnEnter((client) =>
{
client.OnClose(() =>
{
MyClass.RemoveClient(client.UUID);
Console.WriteLine(client.UUID);
});
})
```
- OnExit ``void(TcpClient client)`` <br>
<sub>called when client is disconnected on server</sub>
```cs
TcpServer.OnExit((TcpClient client) =>
{
print($"client disconnected from {client.Host}");
MyClass.RemoveClient(client.UUID);
})
});
```

## Example (dotnet >= 6.0)
<br>

- ##### <return>void</return> OnData(<params>Action&lt;TcpClient, byte[]&gt; callback</params>)
<sub>Event responsible for receiving raw data (buffer) from the client</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>
- <return>Wrapper</return>
```cs
TcpServer.OnEnter((client) =>
{
client.OnData((buffer) =>
{
Console.WriteLine(client.UUID);
});
});
```


<br>


- ##### <return>void</return> OnEvent(<params>Action&lt;TcpClient, string, byte[]&gt; callback</params>)
<sub>Event responsible for receiving events (netly-events) from the client.</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>
- <return>Wrapper</return>
```cs
TcpServer.OnEnter((client) =>
{
client.OnEvent((name, buffer) =>
{
Console.WriteLine(client.UUID);
});
});
```

<br>

- ##### <return>void</return> OnModify(<params>Action&lt;Socket&gt; socket</params>)
<sub>This event is responsible for executing modifications in ``Socket``, this event is executed in the connection creation step, and you will have access to ``Socket`` that will be used internally</sub>
- <sub>``callback`` is the "function" responsible for handling the received event.<sub/>

<br>

## Example
```cs
using System;
using Netly;
Expand Down Expand Up @@ -231,5 +212,4 @@ white(running)
}

Console.WriteLine("Goodbye!!!");

```

0 comments on commit 51222e7

Please sign in to comment.