Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lfex/tcp-client
A simple LFE TCP client connection manager
https://github.com/lfex/tcp-client
beam connection-manager erlang lfe tcp tcp-client
Last synced: 20 days ago
JSON representation
A simple LFE TCP client connection manager
- Host: GitHub
- URL: https://github.com/lfex/tcp-client
- Owner: lfex
- License: apache-2.0
- Created: 2020-12-06T07:29:35.000Z (almost 4 years ago)
- Default Branch: release/0.2.x
- Last Pushed: 2021-06-27T07:36:42.000Z (over 3 years ago)
- Last Synced: 2024-04-27T00:24:31.097Z (7 months ago)
- Topics: beam, connection-manager, erlang, lfe, tcp, tcp-client
- Language: LFE
- Homepage:
- Size: 126 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tcp-client
*A simple LFE TCP client connection manager*
[![Build Status][gh-actions-badge]][gh-actions]
[![LFE Versions][lfe-badge]][lfe]
[![Erlang Versions][erlang-badge]][versions]
[![Tag][github-tag-badge]][github-tag]
[![Project Logo][logo]][logo-large]
## About
This library provides a simple TCP client for use in non-critical BEAM
applications such as command line tools and REPLs. That being said, it _is_
intended to be used from OTP release apps (e.g., making use of configuration
data in `./config/sys.config`).
Exponential backoff for an unavailable TCP server is provided via Fred's
[Erlang backoff library](https://github.com/ferd/backoff).
## Configuration
Update your application's `sys.config` to include the following:
``` erlang
[
%% any other confit entries ...
{'tcp-client', [
{server, [
%% where to connect the client
{host, "localhost"},
{port, 7099},
{options, [
%% gen_tcp options
{tcp, [binary, {active, true}, {packet, 0}]},
%% The M/F responseible for parsing the packet; Func is arity 2,
%% taking the packet data as the first argument and a tuple of
%% the reporter {Mod, Func} as the second argument. This M/F is
%% called by `connect` when a TCP packet is received.
{parser, {Mod, Func}},
%% It is up to the parser to call this next M/F, but the reporter
%% tuple is what gets passed to the paser M/F.
{reporter, {Mod, Func}},
%% Exponential backoff support with initial and max values
{'init-backoff', 500}, % in ms
{'max-backoff', 60000} % in ms
]}
]}
]}
].
```
You will need to update the M/Fs for both the paser and the reporter.
## Usage
Start up the connection manager:
``` lisp
lfe> (application:start 'tcp-client)
```
Send a message that will wait for a response ("call"):
``` lisp
lfe> (tcp-client:call-msg data)
```
Send a message that will return immediately ("cast"):
``` lisp
lfe> (tcp-client:cast-msg data)
```
The [undertone project](https://github.com/lfex/undertone) uses this library
with the following parser and reporter definitions:
``` lisp
(defun parse-response
((packet `#(,reporter-mod ,reporter-func))
(let* ((raw-msgs (split-xt-packet packet))
(msgs (maybe-one-msg raw-msgs)))
(list-comp
((<- x raw-msgs))
(apply reporter-mod reporter-func `(,x)))
(log-debug "Parsed packet: ~p" `(,msgs))
msgs)))
(defun report (data)
(log-debug "Got data from TCP server: ~p" `(,data)))
(defun rcv-delim () #b(0))
(defun split-xt-packet (packet)
(list-comp
((<- x (when (=/= x #b()))
(binary:split packet (rcv-delim) '(global))))
(xt.lang:->lfe x)))
(defun maybe-one-msg
((`(,msg . ()))
msg)
((msgs)
msgs))
```
## Licence
Copyright © 2015, Carlos Andres Bolaños
Copyright © 2019, Andrea Leopardi
Copyright © 2020, Duncan McGreggor
[//]: ---Named-Links---
[logo]: priv/images/logo.png
[logo-large]: priv/images/logo.svg
[github]: https://github.com/lfex/tcp-client
[gh-actions-badge]: https://github.com/lfex/tcp-client/workflows/ci%2Fcd/badge.svg
[gh-actions]: https://github.com/lfex/tcp-client/actions
[lfe]: https://github.com/rvirding/lfe
[lfe-badge]: https://img.shields.io/badge/lfe-2.0-blue.svg
[erlang-badge]: https://img.shields.io/badge/erlang-21%20to%2023-blue.svg
[versions]: https://github.com/lfex/tcp-client/blob/master/.github/workflows/cicd.yml
[github-tag]: https://github.com/lfex/tcp-client/tags
[github-tag-badge]: https://img.shields.io/github/tag/lfex/tcp-client.svg
[github-downloads]: https://img.shields.io/github/downloads/lfex/tcp-client/total.svg