<commit_before>Name
====

dynamic-upstream-module-lua - Lua bindings for dynamic-upstream-module

Table of Contents
=================

* [Name](#name)
* [Status](#status)
* [Synopsis](#synopsis)
* [Description](#description)
* [Methods](#methods)
    * [get_upstreams](#get_upstreams)
    * [get_peers](#get_peers)
    * [get_primary_peers](#get_primary_peers)
    * [get_backup_peers](#get_backup_peers)
    * [set_peer_down](#set_peer_down)
    * [set_peer_up](#set_peer_up)
    * [add_primary_peer](#add_primary_peer)
    * [add_backup_peer](#add_backup_peer)
    * [remove_peer](#remove_peer)
    * [update_peer](#update_peer)

Dependencies
============

This module has several dependencies:
* [dynamic-upstream-module](https://github.com/ZigzagAK/ngx_dynamic_upstream)

Status
======

This library is still under early development but is already production ready.

Description
===========

This module provides Lua bindings to manage content of nginx upstreams.

[Back to TOC](#table-of-contents)

Synopsis
========

```nginx
http {
    lua_package_path "/path/to/lua-ngx-dynamic-upstream-lua/lib/?.lua;;";

    upstream backend {
        zone backend 1m;
        server 127.0.0.1:9090;
    }

    lua_socket_log_errors off;

    server {
        listen 9090;
        listen 9091;
        
        default_type text/plain;
        
        location / {
          return 200 'Hello world!';
        }
    }
    
    server {
        listen 8888;

        default_type text/plain;

        # add peer
        # curl "http://localhost:8888/backend/add?peer=127.0.0.1:9091"
        location ~* ^/(.+)/add {
          set $upstream $1;
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"

            local peer = ngx.var.arg_peer
            local upstream = ngx.var.upstream
            
            local result, _, err = dynamic_upstream.add_primary_peer(upstream, peer)
            if not result then
              say("Failed to add peer " .. peer .. ": ", err)
              return
            end
            
            local peer_args = {
              weight = 1,
              max_fails = 2,
              fail_timeout = 30,
              down = 1
            }
            
            result, _, err = dynamic_upstream.update_peer(upstream, peer, peer_args)
            if not result then
             ngx.say("Failed to update peer " .. peer .. " params, error: ", err)
             return
            end
            
            ngx.say("Added " .. peer .. " to " .. upstream .. " upstream")
          }
        }

        # remove peer
        # curl "http://localhost:8888/backend/remove?peer=127.0.0.1:9091"
        location ~* ^/(.+)/remove {
          set $upstream $1;
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"

            local peer = ngx.var.arg_peer
            local upstream = ngx.var.upstream
            
            local result, _, err = dynamic_upstream.remove_peer(upstream, peer)
            if not result then
              say("Failed to remove peer " .. peer .. ": ", err)
              return
            end

            ngx.say("Removed " .. peer .. " from " .. upstream .. " upstream")
          }
        }
        
        # status page for all the peers:
        location = /status {
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"
            local ok, upstreams, error = dynamic_upstream.get_upstreams()
            if ok then
              for _, upstream in pairs(upstreams)
              do
                ngx.say(upstream)
                local ok, servers, error = dynamic_upstream.get_peers(upstream)
                if ok then
                  for _, server in pairs(servers)
                  do
                    local status = "up"
                    if server.down ~= nil then
                      status = "down"
                    end
                    ngx.say("    server " .. server.name .. " backup=" .. server.backup .. " weight=" .. server.weight .. " max_fails=" .. server.max_fails .. " fail_timeout=" .. server.fail_timeout .. " status=" .. status)
                  end
                else
                  ngx.say(error)
                end
                ngx.say()
              end
            else
              ngx.say(error)
            end
          }
        }
    }
}
```
[Back to TOC](#table-of-contents)

Methods
=======

get_upstreams
-------------
**syntax:** `ok, upstreams, error = dynamic_upstream.get_upstreams()`

**context:** *&#42;_by_lua&#42;*

Get table of upstreams.

Returns true and lua table on success, or false and a string describing an error otherwise.


get_peers
-------------
**syntax:** `ok, servers, error = dynamic_upstream.get_peers(upstream)`
<commit_msg>add stream suppert to README<commit_after>Name
====

dynamic-upstream-module-lua - Lua bindings for dynamic-upstream-module

This module supports http and stream upstream types.

Table of Contents
=================

* [Name](#name)
* [Status](#status)
* [Synopsis](#synopsis)
* [Description](#description)
* [Packages](#packages)
* [Methods](#methods)
    * [get_upstreams](#get_upstreams)
    * [get_peers](#get_peers)
    * [get_primary_peers](#get_primary_peers)
    * [get_backup_peers](#get_backup_peers)
    * [set_peer_down](#set_peer_down)
    * [set_peer_up](#set_peer_up)
    * [add_primary_peer](#add_primary_peer)
    * [add_backup_peer](#add_backup_peer)
    * [remove_peer](#remove_peer)
    * [update_peer](#update_peer)

Dependencies
============

This module has several dependencies:
* [dynamic-upstream-module](https://github.com/ZigzagAK/ngx_dynamic_upstream)

Status
======

This library is production ready.

Description
===========

This module provides Lua bindings to manage content of nginx upstreams.

[Back to TOC](#table-of-contents)

Synopsis
========

```nginx
http {
    lua_package_path "/path/to/lua-ngx-dynamic-upstream-lua/lib/?.lua;;";

    upstream backend {
        zone backend 1m;
        server 127.0.0.1:9090;
    }

    lua_socket_log_errors off;

    server {
        listen 9090;
        listen 9091;
        
        default_type text/plain;
        
        location / {
          return 200 'Hello world!';
        }
    }
    
    server {
        listen 8888;

        default_type text/plain;

        # add peer
        # curl "http://localhost:8888/backend/add?peer=127.0.0.1:9091"
        location ~* ^/(.+)/add {
          set $upstream $1;
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"

            local peer = ngx.var.arg_peer
            local upstream = ngx.var.upstream
            
            local result, _, err = dynamic_upstream.add_primary_peer(upstream, peer)
            if not result then
              say("Failed to add peer " .. peer .. ": ", err)
              return
            end
            
            local peer_args = {
              weight = 1,
              max_fails = 2,
              fail_timeout = 30,
              down = 1
            }
            
            result, _, err = dynamic_upstream.update_peer(upstream, peer, peer_args)
            if not result then
             ngx.say("Failed to update peer " .. peer .. " params, error: ", err)
             return
            end
            
            ngx.say("Added " .. peer .. " to " .. upstream .. " upstream")
          }
        }

        # remove peer
        # curl "http://localhost:8888/backend/remove?peer=127.0.0.1:9091"
        location ~* ^/(.+)/remove {
          set $upstream $1;
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"

            local peer = ngx.var.arg_peer
            local upstream = ngx.var.upstream
            
            local result, _, err = dynamic_upstream.remove_peer(upstream, peer)
            if not result then
              say("Failed to remove peer " .. peer .. ": ", err)
              return
            end

            ngx.say("Removed " .. peer .. " from " .. upstream .. " upstream")
          }
        }
        
        # status page for all the peers:
        location = /status {
          content_by_lua_block {
            local dynamic_upstream = require "ngx.dynamic_upstream"
            local ok, upstreams, error = dynamic_upstream.get_upstreams()
            if ok then
              for _, upstream in pairs(upstreams)
              do
                ngx.say(upstream)
                local ok, servers, error = dynamic_upstream.get_peers(upstream)
                if ok then
                  for _, server in pairs(servers)
                  do
                    local status = "up"
                    if server.down ~= nil then
                      status = "down"
                    end
                    ngx.say("    server " .. server.name .. " backup=" .. server.backup .. " weight=" .. server.weight .. " max_fails=" .. server.max_fails .. " fail_timeout=" .. server.fail_timeout .. " status=" .. status)
                  end
                else
                  ngx.say(error)
                end
                ngx.say()
              end
            else
              ngx.say(error)
            end
          }
        }
    }
}
```
[Back to TOC](#table-of-contents)

Packages
=======

Package `ngx.dynamic_upstream` is used for manipulation http upstreams.
Package `ngx.dynamic_upstream.stream` is used for manipulation stream upstreams.

Functionality of both packages are same.


Methods
=======

get_upstreams
-------------
**syntax:** `ok, upstreams, error = dynamic_upstream.get_upstreams()`

**context:** *&#42;_by_lua&#42;*

Get table of upstreams.

Returns true and lua table on success, or false and a string describing an error otherwise.


get_peers
-------------
**syntax:** `ok, servers, error = dynamic_upstream.get_peers(upstream)`

{'fraction_non_alphanumeric': 0.1229499949693128, 'fraction_numerical': 0.013079786698863064, 'mean_word_length': 1.7040261153427638, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3775525', 'n_tokens_mistral': 3062, 'n_tokens_neox': 2837, 'n_words': 655}