lua-handlers
Provides a set of async. callback based handlers for working with raw TCP/UDP socket, ZeroMQ sockets, or HTTP client/server.
Socket connect/listen URI's
Different types of sockets can now be created from URI strings like tcp://localhost:1234/ or tls:/localhost:443/?key=examples/localhost.key&cert=examples/localhost.cert. URI's can be used for connecting sockets or listening sockets.
TCP sockets
tcp://<hostname or ip_address>:<optional port>/
UDP sockets
udp://<hostname or ip_address>:<optional port>/
Unix domain sockets
unix://<path to unix socket>
SSL/TLS sockets over TCP
tls://<hostname or ip_address>:<optional port>/?mode=<client/server>&key=<path to PEM private key>&cert=<path to PEM public certificate>
To force IPv6 sockets
tcp6://<hostname or ipv6_address>:<optional port>/
udp6://<hostname or ipv6_address>:<optional port>/
tls6://<hostname or ipv6_address>:<optional port>/?mode=<client/server>&key=<path to PEM private key>&cert=<path to PEM public certificate>
Example server-side listen URIs:
-- bind tcp socket to 127.0.0.1 on port 80 with an accept backlog of 1000
tcp://localhost:80/?backlog=1000
-- bind tcp socket to IPv6 address 2001:db8::1 on port 80 with an accept backlog of 1000
tcp://[2001:db8::1]:80/?backlog=1000
-- bind TLS wrapped tcp socket to 127.0.0.1 on port 443 with an accept backlog of 1000
-- TLS defaults to mode=server when listening.
tls://localhost:443/?backlog=1000&key=private_key.pem&cert=public_certificate.pem
-- bind Unix domain socket to file /tmp/unix_server.sock
unix:///tmp/unix_server.sock?backlog=100
-- bind udp socket to 127.0.0.1 on port 53
udp://localhost:53
-- bind udp socket to IPv6 loop back address ::1 on port 53
udp://[::1]:53
or
udp6://localhost:53
Example client-side connect URIs:
-- connect tcp socket to 127.0.0.1 on port 80
tcp://localhost:80
-- connect tcp socket to IPv6 address 2001:db8::1 on port 80
tcp://[2001:db8::1]:80
-- connect tcp socket to IPv6 address of hostname ipv6.google.com on port 80
tcp6://ipv6.google.com:80
-- connect TLS wrapped tcp socket to 127.0.0.1 on port 443
-- TLS defaults to mode=client when connecting.
tls://localhost:443
-- connect Unix domain socket to file /tmp/unix_server.sock
unix:///tmp/unix_server.sock
-- connect udp socket to 127.0.0.1 on port 53
udp://localhost:53
-- connect udp socket to IPv6 loop back address ::1 on port 53
udp://[::1]:53
or
udp6://localhost:53
Set local address & port when connecting
Sockets can be bound to a local address & port before connecting to the remote host:port. For connecting URIs add parameters laddr=<local address>&lport=<local port>.
Examples:
-- connect tcp socket to host www.google.com on port 80 and bind the socket to local address 192.168.0.1
tcp://www.google.com/?laddr=192.168.0.1
-- connect tcp socket to host www.google.com on port 80 and bind the socket to local address 192.168.0.1 and local port 16384
tcp://www.google.com/?laddr=192.168.0.1&lport=16384
-- connect udp socket to 10.0.0.10 on port 53 and bind to local address 10.100.100.1 and port 2053
udp://10.0.0.10:53/?laddr=10.100.100.1&lport=2053
Example generic socket server & client
The generic server can listen on any number of sockets with different types. The clients read stdin and send each line to the server which then re-sends the message to all connected clients.
Start generic socket server: lua examples/generic_chat_server.lua tcp://127.0.0.1:1080/ "tls://127.0.0.1:4433/?key=examples/localhost.key&cert=examples/localhost.cert" tcp://[::1]:1082/ unix:///tmp/test.sock?backlog=1234 udp6://localhost:2053
Start generic socket client: lua examples/generic_chat_client.lua tcp://localhost:1080 -- or lua examples/generic_chat_client.lua udp6://localhost:2053 -- or lua examples/generic_chat_client.lua tls://127.0.0.1:4433/ -- or lua examples/generic_chat_client.lua tcp://[::1]:1082/ -- or lua examples/generic_chat_client.lua unix:///tmp/test.sock
Installing
Install base package lua-handler:
luarocks install "https://github.com/brimworks/lua-ev/raw/master/rockspec/lua-ev-scm-1.rockspec"
luarocks install "https://github.com/Neopallium/nixio/raw/master/nixio-scm-0.rockspec"
luarocks install "https://github.com/Neopallium/lua-handlers/raw/master/lua-handler-scm-0.rockspec"
Install optional sub-package lua-handler-http:
luarocks install "https://github.com/brimworks/lua-http-parser/raw/master/lua-http-parser-scm-0.rockspec"
luarocks install "https://github.com/Neopallium/lua-handlers/raw/master/lua-handler-http-scm-0.rockspec"
Install optional sub-package lua-handler-zmq:
luarocks install "https://github.com/Neopallium/lua-zmq/raw/master/rockspecs/lua-zmq-scm-1.rockspec"
luarocks install "https://github.com/Neopallium/lua-handlers/raw/master/lua-handler-zmq-scm-0.rockspec"
Dependencies
Base lua-handler package required dependcies:
Dependencies for optional lua-handler-http package:
- Lua-ev
- Lua-http-parser
- LuaSocket, needed for the ltn12 sub-module.
Dependencies for optional lua-handler-zmq package:
- Lua-ev
- ZeroMQ requires at least 2.1.0
- ZeroMQ-lua