СТРУКТУРИЗАЦИЯЯЯЯЯ

Author: AMD-NICK

README.MD

@@ -1,9 +1,3 @@
-<!-- personal notes
-
--------
-
--->
-
 # Long Polling Server
 
 A simple [long-polling](https://javascript.info/long-polling) server (and client) written in Lua.
@@ -12,15 +6,6 @@ A simple [long-polling](https://javascript.info/long-polling) server (and client
 
 _source: javascript.info_
 
-## Features:
-
-- Can be used to deliver messages to multiple clients at the same time.
-- Tested in a production environment
-- docker ready
-- Contains Client and Server components. Also contains advanced application example
-- You can specify predefined parameters to be added to each update object, which is useful when you want to recognize different services that send updates to the same link.
-- Ability to customize the amount of data stored and the storage time (for redis) so that no garbage is stored
-
 ## Use cases:
 
 - In environments where it is not possible to create a web server (e.g. in a Garry's Mod game), but getting "webhooks" is necessary
@@ -30,36 +15,41 @@ _source: javascript.info_
 ## Project structure
 
 ```
- .
-├──  lua
-│   └──  long-polling
-│       ├──  application
-│       │   ├──  docker-compose.yml
-│       │   ├──  Dockerfile
-│       │   ├──  init.lua
-│       │   └──  README.MD
-│       ├──  client
-│       │   ├──  init.lua
-│       │   └──  README.MD
-│       └──  server
-│           ├──  dataproviders
-│           │   ├──  localtable.lua
-│           │   └──  redis.lua
-│           ├──  misc
-│           │   ├──  pubsub.lua
-│           │   └──  redis-safe.lua
-│           ├──  init.lua
-│           └──  README.MD
-├──  LICENSE
-└──  README.MD
+│ .
+├── examples
+│   ├── advanced
+│   │   ├── client.lua
+│   │   ├── docker-compose.yml
+│   │   ├── Dockerfile
+│   │   ├── README.MD
+│   │   └── server.lua
+│   └── simple
+│       ├── README.MD
+│       └── server.lua
+├── lua
+│   └── long-polling
+│       ├── dataproviders
+│       │   ├── localtable.lua
+│       │   └── redis.lua
+│       ├── misc
+│       │   ├── pubsub.lua
+│       │   └── redis-safe.lua
+│       └── init.lua
+├── LICENSE
+└── README.MD
 
 ```
 
-## Usage:
+## Documentation:
+
+Not ready yet. I am lazy. **But if you create an issue** so I can see that someone needs it, I will create code documentation instantly ⚡.
+
+But you can look at the examples below to understand what is what. Also, in the examples there are README files with a lot of useful information.
+
+## Application examples:
 
-- 🔥 [application](/lua/long-polling/application)
-- [client](/lua/long-polling/client)
-- [server](/lua/long-polling/server)
+- 🔥 [advanced](/examples/advanced). Source code of real-working application
+- [simple](/examples/simple). Simple to understand example of using the library
 
 ## TODO:
 

examples/advanced/Dockerfile

@@ -3,7 +3,7 @@ FROM ghcr.io/trigonim/lua-express:latest
 RUN luarocks install copas \
 	&& luarocks install lua-cjson \
 	&& luarocks install lua-express-middlewares \
-	&& luarocks install lua-long-polling \
+	# && luarocks install lua-long-polling \
 	&& luarocks install redis-lua
 
 
@@ -14,7 +14,8 @@ EXPOSE 3000
 COPY . /app
 WORKDIR /app
 
-# you can set this by passing this to docker run command
+# you can set this by passing variables to docker run command
 # ENV TZ=
+# ENV LUA_PATH="/app/lua/?.lua;/app/lua/?/init.lua;${LUA_PATH}"
 
 CMD ["lua", "server.lua"]

examples/advanced/README.MD

@@ -1,15 +1,24 @@
-# Long Polling Application
+# Long Polling Server Application
 
-> 🇺🇸 English version not ready for now (I am lazy and don't want to translate it). You can use https://www.deepl.com/ to translate text on your own.
+In this folder you can find the source code of the server and client, which works at `poll.def.pm`.
+
+## Features
+
+- Can be used to deliver messages to multiple clients at the same time.
+- Tested in a production environment
+- docker ready
+- You can specify predefined parameters to be added to each update object, which is useful when you want to recognize different services that send updates to the same link.
+- Ability to customize the amount of data stored and the storage time (for redis) so that no garbage is stored
 
-В папке находится исходный код поллинг клиента и сервера, который работает по адресу `poll.def.pm`.
 
-## Run advanced application
+## Run the application
 
 ```bash
-cd directory_with_this_file/
+# git clone this repo
+# cd directory_with_this_file/
 
 # run server via docker-compose.yml (will build fresh image)
+# 👍 nice for development
 docker-compose up --build polling
 
 # alternatively run server via docker run (will use image from registry)
@@ -32,36 +41,36 @@ No authorization. With API features in mind, you can use your server as a public
 
 **👀 Test server:** poll.def.pm. But please, don't use it in production because I can turn it off at any moment.
 
-# Lua Long Polling Client Example
+## Client Example
 
 > 🇺🇸 English version not ready for now (I am lazy and don't want to translate it). You can use https://www.deepl.com/ to translate text on your own.
 
-Работает как в чистом Lua, так и на Garry's Mod сервере.
+Works both in pure Lua and on Garry's Mod server.
 
-На чистом Lua требует copas (а он luasocket), lua-requests-async (он тоже требует copas) и cjson.
+On pure Lua requires copas (and luasocket), lua-requests-async (it also requires copas) and cjson.
 
-## Использование
+### Usage
 
-**В гмоде** закинуть по любому пути, потом получить доступ к библиотеке через `kupol = include("path/to/client.lua")`. Автоматически в глобальное пространство ничего не добавляется.
+**In gmod** put any file in the path, then get access to the library through `kupol = include("path/to/client.lua")`. Nothing is added to the global space automatically.
 
-В чистом Lua можно использовать `kupol = require("long-polling.client")`.
+In pure Lua you can use `kupol = require("long-polling.client")`.
 
-## Пример
+### Example
 
 ```lua
 local kupol  = require("long-polling.client") -- also works in Garry's Mod with include()
 local Client = kupol.new("https://poll.def.pm/SomeSecretWord")
 
 
--- Получение данных
+-- Getting data
 Client:subscribe(function(upd, last_id)
-	print("LP сервер за все время принял " .. tostring(last_id) .. " обновлений")
-	print("Последнее обновление: " .. kupol.json_encode(upd))
-end, nil, 30) -- 30 это timeout в секундах.
--- nil – это последний id, который был получен (offset)
+	print("LP server received " .. tostring(last_id) .. " updates in all time")
+	print("Last update: " .. kupol.json_encode(upd))
+end, nil, 30) -- 30 is timeout in seconds.
+-- nil – this is the last id, which was received (offset)
 
 
--- Отправка данных
+-- Sending data
 kupol.thread_new(function()
 	for i = 1, 10 do
 		local ok, err = Client:publish({any = "value", counter = i})

examples/advanced/docker-compose.yml

@@ -34,7 +34,7 @@ services:
       - RATE_LIMIT_LIMIT=120
     volumes: # development
       # - $PWD/../../:/app
-      - $PWD/../../lua/long-polling:/usr/local/share/lua/5.1/long-polling
+      - $PWD/../../lua/long-polling:/usr/local/share/lua/5.1/long-polling:ro # luarocks install and lua search path
     init: true # to kill faster via ctrl + c
     # command: lua -e 'while true do end' # if you need to exec bash
     ports:

examples/simple/README.MD

@@ -0,0 +1,13 @@
+# Simple Long Polling Server
+
+This is a simplest realization of long-polling server.
+
+All data is stored in RAM, so it will be lost after server restart.
+
+There is no request logging or error handling features implemented,
+	but you can find it in advanced app file located somewhere in this repo 😅
+
+## API:
+
+- `POST` example.com/any_string?data=any_data => 200 OK
+- `GET ` example.com/any_string?last_id=0&timeout=60 => 200 OK {"any_data"}

examples/simple/server.lua

@@ -0,0 +1,26 @@
+local polling = require("long-polling.server").new("localtable")
+
+local express = require("express")
+local app = express()
+
+local function push_updates(req, res)
+	local channel = req.params.channel
+	local payload = req.query.data
+
+	polling:publish_new(channel, payload)
+	res:send("OK")
+end
+
+local function get_updates(req, res)
+	local channel = req.params.channel
+	local last_id = tonumber(req.query.last_id) or 0
+	local timeout = tonumber(req.query.timeout) or 0
+
+	local data, total = polling:get_news(channel, last_id, timeout)
+	res:set("X-Total-Messages", total):json(data)
+end
+
+app:post("/:channel", push_updates)
+app:get("/:channel", get_updates)
+
+app:listen(3000)