Lua w automatyzacji i narzędziach: skrypty w Nginx, Neovim i systemach wbudowanych

Dlaczego Lua w automatyzacji i narzędziach? Kontekst i realne zastosowania

Rzeczywiste powody popularności Lua: prostota, embedowalność, mały runtime

Lua pojawia się tam, gdzie potrzebny jest lekki, wbudowywalny język skryptowy, a nie kolejny pełnoprawny framework webowy. Sam interpreter jest bardzo mały, łatwy do skompilowania na różne platformy i nie narzuca dużych zależności. Dla twórców narzędzi takich jak Nginx czy Neovim oznacza to, że mogą dać użytkownikom możliwość pisania skryptów bez dźwigania całego środowiska typu Python czy Node.js.

Do tego dochodzi prosta, przewidywalna składnia. Programiści C, JavaScript czy Pythona są w stanie w kilka godzin ogarnąć podstawy Lua, szczególnie jeśli używają go tylko do konfiguracji lub prostych automatów. Lua nie ma rozbudowanego systemu modułów, klas czy wyjątków – dla jednych to wada, ale przy osadzaniu w innych aplikacjach upraszcza integrację.

Istotny jest też deterministyczny charakter środowiska. Interpreter Lua nie narzuca współbieżności, wątków ani skomplikowanego modelu pamięci. To duże ułatwienie w systemach wbudowanych i narzędziach serwerowych, gdzie przewidywalność jest ważniejsza niż „wygodne” abstrakcje. Twórcy Nginx czy firmware do IoT mogą mieć większą kontrolę nad tym, kiedy i jak kod Lua jest wykonywany.

Lua jako „język klejowy” między komponentami

Lua w kontekście automatyzacji działa zwykle jako „język klejowy” łączący komponenty napisane w C, Go, Rust czy innym języku systemowym. Twarde, wydajne części systemu pozostają w języku kompilowanym, a logika biznesowa, konfiguracja, routing czy reguły są przenoszone do skryptów Lua. Dzięki temu można:

• szybko zmieniać logikę bez rekompilacji całej aplikacji,
• przekazać część konfiguracji w ręce administratorów lub power-userów,
• wykonać hot reload konfiguracji lub skryptów, bez zatrzymywania całej usługi (w granicach architektury konkretnego narzędzia).

Lua rzadko zastępuje cały backend czy aplikację. W Nginx służy do skryptowania żądań HTTP, w Neovim do konfiguracji i pisania pluginów, w systemach wbudowanych – do sterowania zachowaniem firmware, ale nie do implementacji całej logiki real-time.

Gdzie Lua ma przewagę nad Pythonem czy JavaScriptem, a gdzie przegrywa

Przewaga Lua pojawia się przede wszystkim tam, gdzie znaczenie ma rozmiar i prostota runtime’u. Interpreter Lua można statycznie dołączyć do binarki, zużywa mało pamięci i startuje bardzo szybko. W porównaniu z Pythonem:

• Lua jest łatwiejsza do osadzenia w istniejącej aplikacji C jako biblioteka,
• nie wymaga pełnej instalacji środowiska, menedżera pakietów, itp.,
• zwykle ma mniejszy narzut przy prostych operacjach.

Z drugiej strony ekosystem Pythona czy Node.js jest nieporównywalnie bogatszy. Jeśli potrzebny jest algorytm ML, rozbudowane biblioteki webowe, narzędzia do testów – Lua wchodzi na przegrane pozycje. Z tego powodu stosuje się ją często jako warstwę nad logiką napisaną w innych językach, zamiast próbować robić w Lua wszystko.

Oceniając, czy Lua jest rozsądnym wyborem, trzeba oddzielić dwa światy:

• wewnątrz istniejącego narzędzia (Nginx, Neovim, firmware) – Lua jest bardzo sensownym wyborem, bo jest częścią ekosystemu tego narzędzia,
• jako główny język nowej aplikacji – zazwyczaj przegrywa z językami z większymi społecznościami i bibliotekami.

Typowe scenariusze: rozszerzanie aplikacji, konfiguracja jako kod, szybkie prototypowanie

W praktyce Lua najczęściej służy do:

• rozszerzania zachowania istniejących aplikacji – np. pisanie własnych filtrów w Nginx, pluginów w Neovim, skryptów w Wiresharku,
• konfiguracji jako kod – zamiast statycznych plików konfiguracyjnych można tworzyć warunkowe, generowane konfiguracje w Lua,
• szybkiego prototypowania logiki – np. testowanie nowego sposobu routingu w Nginx bez zmiany backendu.

Przykładowo: zespół SRE może wykorzystać Lua do wprowadzenia nowej polityki rate limiting w OpenResty, zanim trwale zmieni logikę w głównym backendzie. Taka zmiana wymaga mniej koordynacji, a w razie problemów łatwiej ją wycofać jednym deployem konfiguracji.

Przykłady narzędzi używających Lua

Lista projektów opartych o Lua jest szersza niż Nginx i Neovim:

• OpenResty / lua-nginx-module – rozbudowane skryptowanie Nginx w Lua,
• Redis – skrypty Lua wykonywane atomowo na serwerze Redis,
• Wireshark – dekodery protokołów i rozszerzenia w Lua,
• gry i silniki gier (np. w świecie gier mobilnych) – logika poziomów, AI, eventy w Lua,
• systemy IoT – firmware z wbudowanym interpreterem Lua do skryptowania zachowania urządzeń.

We wszystkich tych przypadkach Lua jest używana jako warstwa nad silnikiem w C/C++ lub innym języku – potwierdza to jej rolę jako języka automatyzacji i konfiguracji, a nie pełnego zamiennika dla back-endu aplikacji.

Podstawowe cechy Lua istotne w automatyzacji

Minimalistyczna składnia i specyficzne konwencje

Lua ma bardzo zwięzłą składnię: if ... then ... end, for ... do ... end, bez nadmiaru konstrukcji. To ułatwia audyt skryptów pod kątem bezpieczeństwa i wydajności. Programy są zwykle krótkie, a struktura kodu jest dosyć przewidywalna.

Pojawiają się jednak nietypowe dla wielu programistów konwencje:

• indeksowanie od 1 – tablice w Lua są z definicji 1-indeksowane, co bywa źródłem błędów przy przechodzeniu z C/JS,
• brak klas w rozumieniu obiektowego programowania – zamiast tego stosuje się tabele + metatabele,
• domyślne wartości nil – usunięcie klucza z tabeli polega na ustawieniu go na nil.

Te różnice mają znaczenie w automatyzacji, bo łatwo popełnić subtelny błąd (np. pętla zaczyna się od 0 zamiast 1, co w Lua zwróci nil, a nie błąd). Przy konfiguracji Nginx czy Neovim taki drobiazg może wywołać trudne do zdiagnozowania zachowanie.

Tabele jako uniwersalna struktura danych

W Lua praktycznie wszystko opiera się na tabelach – pełnią rolę tablic, słowników, obiektów, a nawet modułów. To ułatwia reprezentowanie złożonych konfiguracji w jednym typie danych:

local config = {
  server_name = "example.com",
  routes = {
    { path = "/api", backend = "api_backend" },
    { path = "/static", backend = "static_backend" },
  },
  flags = {
    enable_ab_test = true,
  }
}

Tak zdefiniowaną tabelę można traktować jak zwykłą mapę, listę czy strukturę obiektu. W narzędziach typu OpenResty bardzo często przechowuje się w ten sposób reguły routingu, mapy hostów, definicje limitów – dzięki temu konfiguracja jest czytelna, a jednocześnie można ją generować dynamicznie.

W automatyzacji ważne jest też, że tabele mogą być łatwo serializowane do JSON-a lub redisowych struktur, co ułatwia wymianę danych z zewnętrznymi systemami. Trzeba jednak pilnować, by nie mieszać w jednej tabeli reprezentacji listy i słownika; takie hybrydy szybko prowadzą do bałaganu.

Wydajność i zużycie pamięci: goły Lua vs LuaJIT

Standardowy interpreter Lua jest wystarczająco szybki do większości zadań konfiguracyjnych, ale przy intensywnej logice czy dużym ruchu HTTP LuaJIT robi wyraźną różnicę. LuaJIT kompiluje kod „w locie” do kodu maszynowego, co pozwala:

• skracać czas wykonania pętli i złożonych operacji,
• redukować narzut skryptów przy dużym natężeniu żądań (np. w Nginx),
• utrzymać akceptowalny latency przy więcej niż prostych manipulacjach nagłówkami.

Z drugiej strony LuaJIT ma swoje ograniczenia: brak pełnego wsparcia dla wszystkich platform, pewne różnice w zachowaniu garbage collectora i FFI, brak intensywnie rozwijanego upstreamu w porównaniu do „gołego” Lua. W wielu projektach (np. OpenResty) przyjęła się jednak praktyka używania LuaJIT domyślnie, bo korzyści wydajnościowe są duże.

Interfejs C API i typowe osadzanie Lua w programach

Jednym z kluczowych powodów, dla których Lua zyskała popularność w narzędziach, jest C API. Twórcy aplikacji mogą:

• załadować interpreter Lua jako bibliotekę,
• wystawić do Lua swoje funkcje C jako nowe funkcje globalne lub w modułach,
• wywoływać kod Lua z poziomu C i odwrotnie, przekazując argumenty przez stos Lua.

W praktyce oznacza to, że np. Nginx eksponuje do Lua swój model żądania HTTP, zmienne i funkcje pomocnicze (przez moduł ngx), a Neovim – API edytora (przez vim.api). Lua staje się „skryptowym frontem” dla tych funkcji.

Przy samodzielnym osadzaniu Lua trzeba uważać na zarządzanie pamięcią i bezpieczeństwo – łatwo wystawić do Lua zbyt szerokie API C, które pozwoli skryptom robić rzeczy niepożądane (np. dostęp do całego systemu plików lub sieci bez ograniczeń).

Ograniczenia: ekosystem bibliotek i narzędzi

Lua nie ma tak rozbudowanego standardowego ekosystemu jak Python czy JavaScript. Są menedżery pakietów (np. LuaRocks), ale:

• część paczek jest słabo utrzymywana,
• kompatybilność z różnymi wersjami Lua/LuaJIT bywa problemem,
• często potrzeba kompilacji modułów C, co utrudnia deployment.

Dlatego w automatyzacji rzadko buduje się całość na zewnętrznych bibliotekach Lua. Typowy schemat: podstawowa logika wbudowana w narzędzie (Nginx, Neovim, firmware), a Lua służy do łączenia tych funkcji, ewentualnie z kilkoma sprawdzonymi bibliotekami (JSON, HTTP, Redis).

Lua w Nginx – kiedy ma sens i jakie są alternatywy

Czym jest lua-nginx-module i OpenResty oraz skąd biorą się nieporozumienia

lua-nginx-module to moduł dla Nginx (oryginalnie rozwijany przez OpenResty), który dodaje obsługę Lua bezpośrednio w cyklu życia żądania HTTP. Pozwala pisać dyrektywy typu content_by_lua, access_by_lua czy rewrite_by_lua.

OpenResty to dystrybucja Nginx z wbudowanym lua-nginx-module i zestawem bibliotek Lua (np. do HTTP, Redis, MySQL). W praktyce większość „Nginx+Lua” w produkcji działa właśnie jako OpenResty, a nie czysty Nginx z ręcznie dogranym modułem.

Nieporozumienia biorą się głównie stąd, że część osób traktuje OpenResty jako „framework webowy w Nginx”, podczas gdy jego głównym celem jest warstwa edge / brama API z możliwością pisania logiki w Lua. Próby zrobienia pełnego back-endu wyłącznie w Lua w Nginx często kończą się trudnymi do utrzymania rozwiązaniami.

Kiedy logika w Lua jest lepsza niż w czystym Nginx

Standardowy Nginx daje dużo możliwości: rewrite, map, if, try_files, ale przy bardziej złożonych regułach zaczyna się walka z DSL-em konfiguracji. Lua jest rozsądne, gdy:

• reguły routingu są warunkowe i zależne od wielu nagłówków / cookies,
• potrzebna jest logika A/B testów, feature flagi, routing per użytkownik,
• trzeba pracować z danymi zewnętrznymi (Redis, HTTP call do usługi feature flags),
• konfiguracja w Nginx stała się nieczytelna: zagnieżdżone if, kilkudziesięciolinijkowe map.

Lua pozwala tę logikę wyrazić w normalnym języku programowania i zamknąć w dobrze nazwanej funkcji. To zmniejsza ryzyko pomyłek typowych dla konfiguracji w czystym Nginx, gdzie często trudno „na oko” ogarnąć wszystkie interakcje między dyrektywami.

Granice rozsądku: co zostawić Nginxowi, a co przenieść do backendu

W praktyce sensowna granica wygląda tak:

Rozsądny podział odpowiedzialności między warstwami

Najprostsze i najczęściej działające kryterium: Nginx (z Lua) obsługuje „edge i glue”, a back-end biznes. Da się to ująć w kilka praktycznych zasad:

• Do Nginxa+Lua wkłada się:
  • routing między usługami (service discovery, proste reguły canary),
  • autoryzację techniczną (np. walidacja JWT, podstawowe ACL po nagłówkach),
  • limitowanie ruchu, proste reguły anty-DDoS, „ratelimit per token” z Redisem,
  • normalizację i walidację formatów (np. zamiana starych API na nowe, przepakowanie nagłówków),
  • logowanie, tagowanie żądań, korelację trace ID.
• Do back-endu zostawia się:
  • logikę domenową (płatności, koszyki, workflow, reguły biznesowe),
  • długi stan i skomplikowane transakcje,
  • ciężkie zapytania do baz danych i obliczeniowo drogie operacje.

Jeżeli w Lua zaczyna się pojawiać logika typu „jeśli użytkownik ma > n transakcji w ostatnich m dniach i jest w kraju X, to…”, to zwykle sygnał, że kod wycieka z domeny biznesowej w stronę bramy HTTP. Takie fragmenty robią się trudne do testowania i wersjonowania, a przy większej skali ich refaktoryzacja w środowisku Nginx jest wyraźnie bardziej bolesna niż w normalnej aplikacji.

Alternatywy dla Lua w warstwie edge

Lua nie jest jedyną opcją. Zależnie od ograniczeń organizacyjnych i technicznych, używa się też:

• Kong / APISIX / Tyk – gotowe bramy API, zwykle oparte na OpenResty, ale z warstwą plug-inów w Lua lub w innych językach; oszczędzają konieczność pisania wszystkiego ręcznie,
• Envoy + filtrowanie w Lua / WebAssembly – alternatywa w środowiskach mocno „cloud-native” i service mesh,
• HAProxy z Lua – tam, gdzie HTTP to głównie load balancing i rewrites, a nie pełny edge gateway,
• dedykowane microserwisy w Go/Node/Python, które przejmują rolę bramy (BFF – Backend For Frontend) i robią routing, agregację, translację protokołów.

Lua w Nginx ma sens, gdy i tak potrzebny jest klasyczny Nginx jako reverse proxy, a logika bramy nie jest na tyle rozbudowana, by utrzymywać kolejny serwis z osobnym cyklem życia. Tam, gdzie organizacja ma już silne standardy wokół Envoy / API Gateway w chmurze, dokładanie Lua w Nginx często tylko komplikuje obraz.

Praktyczne wzorce użycia Lua w Nginx (OpenResty)

Struktura projektu: konfig jako „szkielet”, Lua jako implementacja

Konfiguracja Nginx dobrze sprawdza się jako „deklaratywny szkielet”, a pliki Lua – jako miejsce na implementację logiki. Typowy układ:

nginx.conf
conf.d/
  gateway.conf
lua/
  init.lua
  routes/
    router.lua
  auth/
    jwt.lua
  utils/
    redis.lua

W nginx.conf pojawiają się dyrektywy typu:

http {
  lua_package_path "lua/?.lua;;";

  init_by_lua_block {
    require("init").setup()
  }

  server {
    listen 80;

    location /api/ {
      access_by_lua_block {
        require("auth.jwt").check()
      }

      content_by_lua_block {
        require("routes.router").handle()
      }
    }
  }
}

Logika jest wyciągnięta do modułów Lua, które da się testować poza Nginx, przynajmniej w części (np. parsowanie tokenów, podejmowanie decyzji routingu). Konfiguracja pozostaje krótka i służy głównie do określenia, w którym hooku wywołać daną funkcję.

Użycie faz Nginx: rewrite, access, content i log

lua-nginx-module pozwala podpiąć Lua do różnych faz przetwarzania żądania. Typowy podział:

• rewrite_by_lua* – normalizacja URL, przepisywanie ścieżek, prosty routing na podstawie nagłówków,
• access_by_lua* – autoryzacja, ACL, decyzje typu „reject / allow / redirect”,
• content_by_lua* – generowanie odpowiedzi (np. lekki mock, healthcheck, prosta bramka HTTP→HTTP),
• log_by_lua* – dodatkowe logowanie do zewnętrznych systemów, asynchroniczne metryki.

Dzięki temu część kodu może wykonywać się nawet wtedy, gdy Nginx nie przekazuje żądania dalej (np. odrzuca je w fazie access). Pozwala to uniknąć „logiki bezpieczeństwa” rozproszonej po kilku backendach.

Cache i współdzielenie danych: ngx.shared.DICT i pamięć per-worker

OpenResty udostępnia lua_shared_dict, czyli pamięć współdzieloną między workerami Nginx:

lua_shared_dict my_cache 10m;

W Lua wygląda to tak:

local cache = ngx.shared.my_cache

local function get_feature_flag(user_id)
  local key = "flag:" .. user_id
  local v = cache:get(key)
  if v ~= nil then
    return v == 1
  end

  -- np. pobranie z Redisa/HTTP
  local enabled = fetch_flag_from_backend(user_id)

  cache:set(key, enabled and 1 or 0, 60) -- TTL 60s
  return enabled
end

To wygodne przy limitowaniu ruchu, prostych flagach, krótkotrwałym cache’u odpowiedzi. Problem zaczyna się, gdy lua_shared_dict jest traktowany jak „prawie baza danych” – przy większej ilości kluczy bez monitoringu GC i ewikcji można skończyć z trudnymi do debugowania błędami „no memory”.

Współbieżność i asynchroniczność: cosocket i blokujące wywołania

Lua w Nginx działa w modelu współbieżności opartym na kooperatywnych wątkach (coroutines) i „cosocketach”. Istotne konsekwencje:

• nie wolno używać standardowych blokujących socketów ani długich operacji CPU – zablokuje to całego workera,
• zewnętrzne call-e do HTTP/Redis/MySQL powinny używać bibliotek OpenResty (resty.http, resty.redis, itd.),
• logika CPU-intensywna jest z definicji zła kandydatem do uruchamiania w Nginx+Lua (hashowanie, kompresja, długie pętle).

Typowy błąd: „szybki” kod do obliczania jakiegoś złożonego raportu bez I/O, wrzucony do content_by_lua_block, który nagle wystrzela latency przy większym ruchu, bo worker jest skutecznie zablokowany przez CPU.

Wzorce integracji: Redis, feature flags, A/B testing

W praktyce sporo projektów używa Lua głównie jako kleju do usług pomocniczych. Kilka użytecznych schematów:

• Autoryzacja w oparciu o Redis – token/API key w nagłówku, lookup w Redisie w fazie access_by_lua*, decyzja „allow/deny” bez dotykania backendów.
• Feature flags – prosty client HTTP do centralnego serwisu flag, wynik cache’owany w lua_shared_dict lub Redisie; routing do /v1 lub /v2 na podstawie flagi + hash usera.
• A/B testing – deterministyczny wybór wariantu (np. na podstawie user_id % 100) i wstrzyknięcie odpowiednich nagłówków/ciasteczek, resztę robi backend.

We wszystkich tych przypadkach Lua robi głównie „decision engine” na danych z nagłówków, cookies, krótkiego cache’a lub szybkiego backendu typu Redis. Gdy zaczyna potrzebować wielu zapytań HTTP do kilku serwisów, opóźnienia potrafią zjeść większość zysku z przeniesienia logiki „bliżej użytkownika”.

Bezpieczeństwo i stabilność Lua w Nginx

Oddzielenie logiki skryptowej od systemu operacyjnego

Lua w Nginx ma dostęp tylko do tego, co wystawi mu moduł ngx i biblioteki. Sam z siebie nie „widzi” systemu plików ani sieci; dostęp jest pośredni. Ryzyko pojawia się wtedy, gdy:

• wystawia się do Lua własne bindingi w C (np. przez dodatkowe moduły),
• używa się bibliotek Lua, które same otwierają pliki, sockety, procesy.

Przy mniej krytycznych systemach zwykle wystarcza trzymanie się sprawdzonych bibliotek OpenResty i unikanie „magicznych” modułów z LuaRocks. Przy wysokim rygorze bezpieczeństwa dochodzi kwestia sandboxingu – ograniczania globali w Lua, blokowania funkcji typu os.execute (jeśli w ogóle są dostępne) oraz jasnego rozgraniczenia, które moduły require są dozwolone.

Wstrzykiwanie kodu i konfiguracji: dynamiczne lua_code_cache

OpenResty ma mechanizm lua_code_cache, który domyślnie cache’uje załadowane moduły Lua. W środowiskach deweloperskich często ustawia się:

lua_code_cache off;

To wygodne do szybkiego iterowania, ale oznacza, że Nginx każdorazowo ładuje kod z dysku, a ewentualne nadpisanie pliku na serwerze ma natychmiastowy efekt. W produkcji zwyczajowo:

• lua_code_cache zostaje włączone,
• zmiana kodu odbywa się przez normalne wdrożenie + reload Nginx,
• pliki Lua mają takie same zasady dostępu jak pliki binarne aplikacji (CI/CD, podpisy, review).

Próby dynamicznego wczytywania fragmentów Lua z bazy/Redisa lub HTTP („konfiguracja jako kod w bazie”) otwierają oddzielną kategorię problemów bezpieczeństwa. Jeżeli koniecznie trzeba to robić, minimalnym wymogiem jest walidacja, podpisy kryptograficzne lub ograniczenie zestawu dozwolonych konstrukcji.

Odporność na błędy: pcall, xpcall i kontrola wyjątków

Lua nie ma wyjątków w stylu Pythona – używa mechanizmu error/pcall. W Nginx:

• nieobsłużony błąd w Lua kończy się statusem 500 i logiem błędu,
• „pułapka” w newralgicznym miejscu może rozsypać sporą część ruchu.

Fragmenty, które korzystają z zewnętrznych systemów (HTTP, Redis, parsowanie danych wejściowych), dobrze jest opakować:

local ok, err = pcall(function()
  do_something_risky()
end)

if not ok then
  ngx.log(ngx.ERR, "lua error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

Nadużywanie pcall prowadzi do sytuacji, w której wszystkie błędy są sprowadzane do „500 wewnętrzny błąd”, a przyczynę zakopuje się w logach. Z drugiej strony kod bez żadnej ochrony bywa zbyt kruchy przy nieprzewidzianych przypadkach (dziwne nagłówki, przerwy w Redisie).

Ograniczenia czasowe i zasobów: lua_socket_log_errors, timeouts, limits

Większość bibliotek OpenResty ma jawne timeouty. Jeśli nie zostaną ustawione, czasem korzystają z domyślnych wartości, które są nieadekwatne do konkretnej instalacji. Niewinna konstrukcja typu:

local http = require "resty.http"
local client = http.new()
local res, err = client:request_uri("http://flags/api")

może w warunkach problemów sieciowych oznaczać wiszące żądania i powolne zatykanie workerów. Sensowne minimum:

client:set_timeouts(100, 200, 200) -- connect, send, read (ms)

Do tego dochodzą limity per-upstream w Nginx (liczba połączeń, kolejki) i logowanie błędów socketów. Gdy włącza się rozszerzone logowanie (lua_socket_log_errors), łatwiej odróżnić problemy kodu od problemów infrastruktury.

Lua w Neovim – od „lepszego Vimrc” do własnych narzędzi

Dlaczego Neovim postawił na Lua

Neovim odciął się od klasycznego modelu Vimscript jako głównego języka konfiguracji i pluginów. Lua stała się pierwszoplanowa z kilku powodów:

• jest szybka i mało zasobożerna – istotne przy częstym wywoływaniu hooków w edytorze,
• ma prosty embedding, więc integracja z C core Neovima jest stosunkowo bezbolesna,
• łatwiej na niej zbudować API do użycia przez autorów pluginów, niż dalej rozbudowywać Vimscript.

Nie oznacza to, że Vimscript zniknął – działa przez warstwę zgodności. Jednak przy nowych konfiguracjach i pluginach Lua jest naturalnym wyborem, bo ma pełny dostęp do vim.api oraz lepsze wsparcie narzędzi (LSP, formatery, lint).

Typowe poziomy „wejścia” w Lua w Neovimie

Użytkownicy zwykle przechodzą trzy etapy:

1. Zastąpienie vimrc konfiguracją w Lua – mapowania, opcje, proste komendy,

Drugi etap: konfiguracja jako kod – moduły, struktura, narzędzia

Po przepisaniu podstawowych ustawień na Lua zwykle przychodzi czas na uporządkowanie plików i rozbicie wszystkiego na moduły. Zamiast jednego gigantycznego init.lua łatwiej utrzymać drzewo:

~/.config/nvim/
├── init.lua
└── lua/
    └── user/
        ├── options.lua
        ├── keymaps.lua
        ├── plugins.lua
        ├── lsp.lua
        ├── treesitter.lua
        └── ui.lua

W init.lua konfiguracja ogranicza się do wywołania modułów:

require("user.options")
require("user.keymaps")
require("user.plugins")
require("user.lsp")
require("user.treesitter")

Przewaga nad klasycznym Vimscript polega na tym, że można używać zwykłych funkcji, zmiennych lokalnych i warunków. Przykład warunkowej konfiguracji per system:

local is_linux = vim.loop.os_uname().sysname == "Linux"

if is_linux then
  vim.o.clipboard = "unnamedplus"
else
  vim.o.clipboard = ""
end

Tego typu logika w Vimscript bywała dużo bardziej kłopotliwa w utrzymaniu. Zbyt rozbudowane drzewa modułów mają jednak drugą stronę – debugowanie staje się trudniejsze, gdy logika opcji i pluginów jest rozproszona po kilkunastu plikach. Z czasem zwykle powstaje granica: osobne moduły dla „warstw” (LSP, UI, ruch w plikach), ale bez rozdrabniania na każdy plugin z osobnym katalogiem.

Trzeci etap: Neovim jako platforma – własne komendy i mini‑narzędzia

Na kolejnym poziomie Lua służy już nie tylko do ustawiania opcji, ale do budowania własnych komend i prostych aplikacji w ramach Neovima. Typowe przypadki:

• skrypty do powtarzalnych operacji na repozytoriach (formatowanie, lint, build, uruchamianie testów),
• narzędzia przeglądające logi lub JSON bez opuszczania edytora,
• interaktywne panele (np. do przełączania feature flag lokalnie, przeglądania branchy git, odpytania API).

Kluczowe jest tu vim.api – zestaw funkcji pozwalających tworzyć bufory, okna, komendy i mapowania. Minimalny przykład „narzędzia” do szybkiego otwierania dokumentacji projektu:

local M = {}

function M.open_docs()
  local docs_path = vim.fn.getcwd() .. "/docs/README.md"
  if vim.fn.filereadable(docs_path) == 0 then
    vim.notify("Brak docs/README.md", vim.log.levels.WARN)
    return
  end
  vim.cmd("vsplit " .. vim.fn.fnameescape(docs_path))
end

vim.api.nvim_create_user_command("ProjectDocs", M.open_docs, {})

return M

Tego typu moduły szybko przestają być „konfiguracją” w tradycyjnym sensie. To już kod biznesowy, tylko że ściśle powiązany z ergonomią pracy w projekcie. Tu pojawia się pierwsza pułapka: jeżeli narzędzie jest zbyt mocno przywiązane do indywidualnych nawyków, trudno je później współdzielić z zespołem albo opublikować jako plugin.



Praktyczna konfiguracja Neovim w Lua krok po kroku

Punkt wyjścia: init.lua zamiast init.vim

Najprostsza ścieżka migracji to stworzenie pliku init.lua obok istniejącego init.vim. Neovim, jeśli znajdzie oba, priorytetowo potraktuje Lua. Przykładowe minimum:

-- ~/.config/nvim/init.lua

-- podstawowe opcje
vim.o.number = true
vim.o.relativenumber = true
vim.o.expandtab = true
vim.o.shiftwidth = 2
vim.o.tabstop = 2

-- proste mapowanie
vim.keymap.set("n", "<leader>ff", function()
  vim.cmd("Telescope find_files")
end, { desc = "Find files" })

Warto od razu wypracować prostą konwencję: brak logiki w init.lua, tylko require oraz ewentualne rzeczy absolutnie bazowe (np. ustawienie lidera). Klasyczny błąd to trzymanie wszystkich mapowań w jednym pliku i mieszanie ich z konfiguracją pluginów, co z czasem prowadzi do niejasnych zależności.

Opcje i mapowania w oddzielnych modułach

Podział opcji i skrótów na osobne moduły ogranicza ilość efektów ubocznych. Przykładowy lua/user/options.lua:

local o = vim.o
local wo = vim.wo
local bo = vim.bo

o.termguicolors = true
o.clipboard = "unnamedplus"
o.updatetime = 300

wo.number = true
wo.relativenumber = true

bo.swapfile = false

A w lua/user/keymaps.lua:

local map = vim.keymap.set
local opts = { noremap = true, silent = true }

vim.g.mapleader = " "

map("n", "<leader>w", "<cmd>write<cr>", opts)
map("n", "<leader>q", "<cmd>quit<cr>", opts)

map("n", "<C-h>", "<C-w>h", opts)
map("n", "<C-j>", "<C-w>j", opts)
map("n", "<C-k>", "<C-w>k", opts)
map("n", "<C-l>", "<C-w>l", opts)

Taki podział jest dość banalny, ale zmniejsza ryzyko, że konfiguracja jakiegoś pluginu nieświadomie nadpisze globalne opcje albo odwrotnie. Jeśli mapowania stają się skomplikowane, dobrym kompromisem bywa osobny moduł per „obszar” (np. git.lua, telescope.lua, lsp_keymaps.lua), zamiast jednego pliku dla całego edytora.

Menadżer pluginów a Lua: lazy.nvim, packer.nvim i inni

W ekosystemie Neovima przeważyły menadżery konfigurujące pluginy w Lua. Najczęściej spotykane obecnie są:

• lazy.nvim – agresywne leniwe ładowanie, rozbudowane deklaratywne API,
• packer.nvim – od dawna popularny, nadal używany w wielu konfiguracjach,
• folke/lazy.nvim de facto zaczyna być domyślną opcją dla nowych setupów.

Przykładowa minimalna konfiguracja lazy.nvim:

-- lua/user/plugins.lua
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git",
    "clone",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable",
    lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

require("lazy").setup({
  { "nvim-lua/plenary.nvim" },
  {
    "nvim-telescope/telescope.nvim",
    dependencies = { "nvim-lua/plenary.nvim" },
    cmd = "Telescope",
  },
  {
    "nvim-treesitter/nvim-treesitter",
    build = ":TSUpdate",
  },
})

Deklaracje w tabelkach zamiast komend Vimscript są wygodne, ale mają wady: łatwo przesadzić z warunkami i callbackami w definicjach pluginów, przez co moduł plugins.lua zamienia się w mały framework. Dobrą praktyką jest wyprowadzenie konfiguracji konkretnych pluginów do osobnych modułów i odwoływanie się do nich z poziomu config = function() ... end.

Konfiguracja LSP w Lua: minimum działającej komunikacji

Oficjalny plugin nvim-lspconfig zapewnia sensowne domyślne ustawienia, ale konfiguracja w dużych projektach szybko się komplikuje. Najprostszy działający przykład:

-- lua/user/lsp.lua
local lspconfig = require("lspconfig")

local on_attach = function(client, bufnr)
  local bufmap = function(mode, lhs, rhs)
    vim.keymap.set(mode, lhs, rhs, { buffer = bufnr, silent = true })
  end

  bufmap("n", "gd", vim.lsp.buf.definition)
  bufmap("n", "gr", vim.lsp.buf.references)
  bufmap("n", "K", vim.lsp.buf.hover)
end

local capabilities = vim.lsp.protocol.make_client_capabilities()

lspconfig.lua_ls.setup({
  on_attach = on_attach,
  capabilities = capabilities,
  settings = {
    Lua = {
      diagnostics = { globals = { "vim" } },
    },
  },
})

Naturalna pokusa to gromadzenie wszystkich serwerów LSP w jednym module i stosowanie rozbudowanych warunków per język. Przy większej liczbie projektów szybciej sprawdza się podejście odwrotne: osobne pliki dla kluczowych języków (np. lsp/javascript.lua, lsp/go.lua) i prosty „rejestr” w lsp/init.lua, niż jeden potworny setup_all_servers().

Treesitter, statusline, Telescope – trzy typowe filary

W większości nowoczesnych konfiguracji Lua kręci się wokół trzech rozszerzeń:

• nvim-treesitter – parser składni i bazowa funkcjonalność tekstowa,
• statusline (np. lualine.nvim) – dynamiczny pasek stanu,
• Telescope – „fuzzy finder” oparty na Lua, kluczowy przy pracy z dużymi repozytoriami.

Przykładowa konfiguracja Treesitter:

-- lua/user/treesitter.lua
require("nvim-treesitter.configs").setup({
  ensure_installed = { "lua", "python", "go", "javascript" },
  highlight = { enable = true },
  indent = { enable = true },
})

I minimalne lualine:

-- lua/user/ui.lua
require("lualine").setup({
  options = {
    theme = "auto",
    icons_enabled = true,
    section_separators = "",
    component_separators = "",
  },
})

Rozsądnym podejściem jest na początku trzymać te konfiguracje możliwie proste. Komplikacja przychodzi naturalnie (niestety), gdy zaczyna się dopisywać własne komponenty do statusline albo własne pickery w Telescope. Wówczas Lua staje się już nie tyle „konfiguracją pluginu”, co pełnoprawnym kodem narzędziowym.

Lua jako język pluginów i mini‑aplikacji w Neovim

Modele rozszerzania: od prostych modułów do pełnych pluginów

Lua w Neovimie umożliwia kilka poziomów tworzenia rozszerzeń:

1. zwykłe moduły w katalogu lua/, używane tylko lokalnie,
2. „pół‑pluginy” w osobnym repo, bez formalnej struktury runtimepath,
3. pełne pluginy z katalogami plugin/, lua/<nazwa>/, README, testami.

Przejście z pierwszej do ostatniej formy rzadko jest jednorazowym skokiem. Częściej wygląda to tak, że szczególnie przydatny moduł po prostu zostaje wydzielony do osobnego repozytorium i dopiero z czasem otrzymuje dokumentację, testy i przemyślane API. W praktyce regułą jest, że pierwszy „plugin” to tak naprawdę rozszerzona konfiguracja jednego zespołu, dopiero potem ewoluuje w coś bardziej uniwersalnego.

Tworzenie komend użytkownika i autokomend

API Neovima pozwala deklarować komendy i autokomendy z poziomu Lua, bez potrzeby pisania Vimscriptu. Podstawowy przykład:

-- lua/user/commands.lua
local api = vim.api

api.nvim_create_user_command("TrimTrailingWhitespace", function()
  local save = vim.fn.winsaveview()
  vim.cmd([[%s/s+$//e]])
  vim.fn.winrestview(save)
end, { desc = "Usuń spacje na końcu linii" })

api.nvim_create_autocmd("BufWritePre", {
  pattern = { "*.lua", "*.py", "*.go" },
  callback = function()
    vim.cmd("TrimTrailingWhitespace")
  end,
})

Ta konstrukcja ma subtelną wadę: zawiera mieszankę vim.cmd i Lua. Przy większych narzędziach przydaje się reguła: logika w Lua, a vim.cmd tylko tam, gdzie nie ma dobrego odpowiednika w API. W przeciwnym razie plugin zaczyna powielać problemy starego Vimscriptu, tylko w innym języku.

Bufory „pseudoterminalowe” i interaktywne panele

Więcej możliwości daje tworzenie własnych buforów i okien, często w trybie nofile jako interfejs użytkownika. Prosty panel wyświetlający ostatnie logi narzędzia:

local M = {}

local function create_log_buf()
  local buf = vim.api.nvim_create_buf(false, true)
  vim.bo[buf].buftype = "nofile"
  vim.bo[buf].bufhidden = "wipe"
  vim.bo[buf].filetype = "mytool-log"
  return buf
end

function M.show_logs(lines)
  local buf = create_log_buf()
  vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)

  local width = math.floor(vim.o.columns * 0.6)
  local height = math.floor(vim.o.lines * 0.4)
  local row = math.floor((vim.o.lines - height) / 2)
  local col = math.floor((vim.o.columns - width) / 2)

  local win = vim.api.nvim_open_win(buf, true, {
    relative = "editor",
    row = row,
    col = col,
    width = width,
    height = height,
    style = "minimal",
    border = "rounded",
  })

  vim.keymap.set("n", "q", function() vim.api.nvim_win_close(win, true) end,
    { buffer = buf, nowait = true, silent = true })
end

return M

Takie mini‑aplikacje tworzą wrażenie „desktopowych” narzędzi w obrębie samego edytora. Z rdzenia Neovima korzysta się tu głównie jako z biblioteki do zarządzania oknami i wejściem użytkownika.

Najczęściej zadawane pytania (FAQ)

Do czego praktycznie używa się Lua w Nginx i OpenResty?

Lua w Nginx (głównie przez OpenResty lub lua-nginx-module) służy do skryptowania zachowania serwera na etapie przetwarzania żądania: modyfikowania nagłówków, implementacji niestandardowego routingu, walidacji żądań, prostych reguł bezpieczeństwa czy rate limitingu. Kluczowe jest to, że logikę można zmieniać bez rekompilacji Nginx i często bez twardego restartu procesu.

Typowy scenariusz to: backend wciąż działa w Go/Java/Node, a Lua tylko decyduje, gdzie trafi żądanie, czy ma być przepuszczone, ograniczone, albo przekonfigurowane „w locie”. Pełnego backendu HTTP raczej się w Lua nie pisze – to warstwa „kleju” nad szybkim serwerem i istniejącą infrastrukturą.

Czy Lua nadaje się jako główny język backendu zamiast Pythona lub Node.js?

Technicznie da się napisać backend w czystym Lua, ale w większości przypadków to słaby wybór. Ekosystem bibliotek, narzędzi, frameworków webowych czy rozwiązań do testów jest o kilka rzędów wielkości uboższy niż w Pythonie czy JavaScripcie. Trzeba więcej rzeczy budować samemu albo korzystać z mniej dojrzałych projektów.

Lua sprawdza się dużo lepiej jako język osadzony w istniejącym narzędziu: w Nginx do logiki HTTP, w Redisie do skryptów atomowych, w Neovim do konfiguracji i pluginów. Gdy projekt zaczyna jako niezależna aplikacja biznesowa, zwykle rozsądniej wybrać język z większą społecznością i gotowymi rozwiązaniami – Lua jest wtedy raczej uzupełnieniem niż fundamentem.

Dlaczego narzędzia takie jak Neovim czy Wireshark wybrały Lua zamiast Pythona?

Główne powody to rozmiar i prostota runtime’u. Interpreter Lua jest mały, łatwo go statycznie dołączyć do binarki i nie wymaga pełnej instalacji środowiska ani zewnętrznego menedżera pakietów. Dla twórców narzędzia oznacza to mniejsze zależności, prostszy proces budowania i przewidywalne zachowanie na różnych platformach.

Druga kwestia to integracja z kodem w C. Lua ma proste i przewidywalne C API, a samo środowisko nie wymusza złożonych modeli współbieżności czy zarządzania pamięcią. To ułatwia wbudowanie go w edytor (Neovim), analizator sieci (Wireshark) czy firmware. Python lub Node oferują więcej bibliotek, ale ich runtime jest cięższy i trudniejszy do osadzenia w „ciasnych” narzędziach.

Czym różni się zwykłe Lua od LuaJIT i kiedy warto użyć LuaJIT?

Standardowe Lua jest interpreterem z prostym GC i bez JIT, co wystarcza do większości zadań konfiguracyjnych i automatyzacji o umiarkowanej skali. LuaJIT dodaje kompilację JIT, dzięki czemu pętle, obliczenia i intensywna logika działają zauważalnie szybciej – to ma znaczenie przy dużym ruchu HTTP, rozbudowanych filtrach w Nginx czy masowej obróbce danych.

LuaJIT ma jednak ograniczenia: nie wspiera w pełni wszystkich architektur i bywa gorzej utrzymywany niż oficjalne Lua. W projektach takich jak OpenResty jest często używany domyślnie, ale w nowych, długowiecznych systemach wbudowanych trzeba świadomie ocenić, czy zależność od LuaJIT i jego FFI jest akceptowalna na docelowych platformach.

Jak Lua wypada pod względem wydajności i pamięci w porównaniu z Pythonem?

Przy typowych zadaniach automatyzacyjnych Lua ma mniejszy narzut niż Python: interpreter startuje szybciej, zużywa mniej pamięci, a integracja z C nie wymaga ciężkich bindingów. Do prostych operacji, konfiguracji i logiki „na krawędzi” (np. Nginx) często daje zauważalnie lepszą gęstość wydajności na MB RAM.

Trzeba jednak oddzielić dwa światy. Dla wbudowanego runtime’u w narzędziu lub firmware – Lua zwykle wygrywa prostotą i rozmiarem. Dla samodzielnej aplikacji z bogatą logiką biznesową, ML, raportowaniem i integracjami – Python zjada Lua ekosystemem bibliotek, mimo wyższego narzutu środowiska.

Jakie są typowe pułapki przy pisaniu skryptów Lua do automatyzacji?

Najczęstszy problem to różnice w modelu danych i konwencjach w porównaniu z C/JS/Pythonem. Tablice są 1-indeksowane, więc pętle zaczynające się od 0 zwracają nil bez błędu, co potrafi długo umykać w konfiguracji Nginx czy Neovim. Nie ma klas w klasycznym sensie, więc próby odwzorowania „pełnego OOP” kończą się zwykle przekombinowanymi tabelami i metatabelami.

Druga pułapka to „hybrydowe” tabele używane jednocześnie jako lista i mapa. Przy automatyzacji i dynamicznym generowaniu konfiguracji szybko powstaje bałagan, trudny do serializacji i debugowania. W praktyce lepiej jasno rozdzielać role: tabela-lista albo tabela-słownik, a nie losowa mieszanka obu.

Kiedy ma sens przeniesienie logiki do Lua, a kiedy lepiej trzymać się głównego języka aplikacji?

Lua ma sens, gdy logika ma być:

• łatwo modyfikowalna bez rekompilacji (np. routing, reguły bezpieczeństwa, polityki limitów),
• konfigurowalna przez administratorów lub power-userów,
• wykonywana blisko krawędzi systemu – w Nginx, Redisie, edytorze, firmware.

W takich miejscach zyskujesz elastyczność bez obciążania narzędzia ciężkim runtime’em.

Jeśli logika jest centralną częścią biznesu, wymaga rozbudowanego ekosystemu (ML, raporty, integracje, testy end-to-end), albo ma być rozwijana przez duży zespół z mieszanym doświadczeniem, częściej lepiej utrzymać ją w głównym języku aplikacji. Lua zostaje wtedy przy automatyzacji „na obrzeżach” – dokładnie tam, gdzie jest najsilniejsza.