Added swagger documentation to REST API

scripts/lua/rest/v2/get/host/data.lua

@@ -1,131 +1,544 @@
 --
 -- (C) 2013-26 - ntop.org
 --
-
 local dirs = ntop.getDirs()
 package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path
 
+-- Required modules for API functionality
 require "lua_utils"
-local json = require ("dkjson")
+local json = require("dkjson")
 local tracker = require("tracker")
 local rest_utils = require("rest_utils")
 
---
--- Read information about a host
--- Example: curl -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "1", "host" : "192.168.1.1"}' http://localhost:3000/lua/rest/v2/get/host/data.lua
---
--- NOTE: in case of invalid login, no error is returned but redirected to login
---
+--- @module host_data_api
+-- @description REST API endpoint for retrieving detailed host information
+-- @version 2.0
+-- @author ntop.org
+-- @license Proprietary
 
-local rc = rest_utils.consts.success.ok
-local res = {}
+--- @swagger
+-- /lua/rest/v2/get/host/data.lua:
+--   get:
+--     tags:
+--       - Host Management
+--       - Monitoring
+--     summary: Retrieve comprehensive information about a network host
+--     description: |
+--       ## Overview
+--       This endpoint provides detailed information about a specific host on a monitored network interface.
+--       It can return basic host statistics, active flows, and protocol-level throughput analysis.
+--       
+--       ## Authentication
+--       - HTTP Basic Authentication with administrator credentials required
+--       - Invalid credentials result in redirection to login page (HTTP 302)
+--       
+--       ## Rate Limiting
+--       - Standard API rate limits apply (100 requests/minute per IP)
+--       
+--       ## Data Sources
+--       - Real-time interface data via ntopng engine
+--       - Flow data from packet processing pipeline
+--       - Protocol classification via nDPI
+--       
+--     parameters:
+--       - name: ifid
+--         in: query
+--         schema:
+--           type: integer
+--           minimum: 1
+--           maximum: 255
+--         required: true
+--         description: |
+--           Network Interface Identifier.
+--           Corresponds to interface index in ntopng.
+--           Use 0 for all interfaces (if supported).
+--         example: 1
+--       
+--       - name: host
+--         in: query
+--         schema:
+--           type: string
+--           pattern: '^([0-9]{1,3}\.){3}[0-9]{1,3}(@[0-9]{1,4})?$|^([0-9a-fA-F:]+)(@[0-9]{1,4})?$'
+--         required: true
+--         description: |
+--           Host IP address with optional VLAN tag.
+--           Formats:
+--           - IPv4: "192.168.1.1"
+--           - IPv4 with VLAN: "192.168.1.1@100"
+--           - IPv6: "2001:db8::1"
+--           - IPv6 with VLAN: "2001:db8::1@200"
+--         example: "192.168.1.1"
+--       
+--       - name: host_stats
+--         in: query
+--         schema:
+--           type: string
+--           enum: ["true", "false", "1", "0"]
+--           default: "true"
+--         required: false
+--         description: |
+--           Control inclusion of host statistics in response.
+--           - "true" or "1": Include host metrics (default)
+--           - "false" or "0": Exclude host metrics
+--           
+--           Host statistics include:
+--           - Traffic volumes (bytes sent/received)
+--           - Packet counts
+--           - Hostname (if resolved)
+--           - ASN information
+--           - Geographic location
+--         example: "true"
+--       
+--       - name: host_stats_flows
+--         in: query
+--         schema:
+--           type: string
+--           enum: ["true", "false", "1", "0"]
+--           default: "false"
+--         required: false
+--         description: |
+--           Control inclusion of flow statistics in response.
+--           When enabled, returns active flows for the host.
+--           
+--           Flow statistics include:
+--           - Active connections
+--           - Protocol distribution
+--           - Throughput per flow
+--           - TCP state information
+--         example: "false"
+--       
+--       - name: limit
+--         in: query
+--         schema:
+--           type: integer
+--           minimum: 1
+--           maximum: 100000
+--           default: 99999
+--         required: false
+--         description: |
+--           Maximum number of flows to return when host_stats_flows is enabled.
+--           Use for performance optimization with hosts having many active connections.
+--           
+--           Note: Actual limit may be lower based on system resources.
+--         example: 100
+--     
+--     produces:
+--       - application/json
+--     
+--     responses:
+--       200:
+--         description: |
+--           Successful response containing host information.
+--           Structure varies based on requested parameters.
+--         content:
+--           application/json:
+--             schema:
+--               oneOf:
+--                 - $ref: '#/components/schemas/HostBasicInfo'
+--                 - $ref: '#/components/schemas/HostWithFlowsInfo'
+--             examples:
+--               basic_response:
+--                 summary: Basic host information (host_stats=true, host_stats_flows=false)
+--                 value:
+--                   ip: "192.168.1.1"
+--                   name: "workstation-01.local"
+--                   localhost: true
+--                   bytes:
+--                     sent: 1524789321
+--                     rcvd: 984532147
+--                   packets:
+--                     sent: 1254789
+--                     rcvd: 985632
+--               flows_response:
+--                 summary: Host information with flows (host_stats_flows=true)
+--                 value:
+--                   ip: "192.168.1.1"
+--                   bytes:
+--                     sent: 1524789321
+--                     rcvd: 984532147
+--                   flows:
+--                     - srv.ip: "192.168.1.1"
+--                       cli.ip: "8.8.8.8"
+--                       proto.ndpi: "DNS"
+--                       bytes: 1250
+--                   ndpiThroughputStats:
+--                     DNS:
+--                       cli2srv:
+--                         throughput_bps: 1250
+--                         throughput_pps: 2
+--       400:
+--         description: |
+--           Invalid request parameters.
+--           Common causes:
+--           - Missing required parameters
+--           - Invalid interface ID
+--           - Malformed host IP address
+--         content:
+--           application/json:
+--             schema:
+--               $ref: '#/components/schemas/ErrorResponse'
+--       401:
+--         description: |
+--           Authentication required or invalid credentials.
+--           Note: Browser clients are redirected to login page.
+--         headers:
+--           Location:
+--             description: Redirect to login page
+--             schema:
+--               type: string
+--       404:
+--         description: |
+--           Host not found on specified interface.
+--           Possible reasons:
+--           - Host is not active
+--           - Interface monitoring is disabled
+--           - Host IP is incorrect
+--         content:
+--           application/json:
+--             schema:
+--               $ref: '#/components/schemas/ErrorResponse'
+--       500:
+--         description: Internal server error
+--         content:
+--           application/json:
+--             schema:
+--               $ref: '#/components/schemas/ErrorResponse'
+--     
+--     components:
+--       schemas:
+--         HostBasicInfo:
+--           type: object
+--           properties:
+--             ip:
+--               type: string
+--               description: Host IP address
+--             name:
+--               type: string
+--               description: Resolved hostname (if available)
+--             localhost:
+--               type: boolean
+--               description: True if host is local to the monitored network
+--             bytes:
+--               type: object
+--               properties:
+--                 sent:
+--                   type: integer
+--                   format: int64
+--                 rcvd:
+--                   type: integer
+--                   format: int64
+--             packets:
+--               type: object
+--               properties:
+--                 sent:
+--                   type: integer
+--                 rcvd:
+--                   type: integer
+--         HostWithFlowsInfo:
+--           allOf:
+--             - $ref: '#/components/schemas/HostBasicInfo'
+--             - type: object
+--               properties:
+--                 flows:
+--                   type: array
+--                   items:
+--                     $ref: '#/components/schemas/FlowInfo'
+--                 ndpiThroughputStats:
+--                   type: object
+--                   additionalProperties:
+--                     $ref: '#/components/schemas/ProtocolThroughput'
+--                 flows_count:
+--                   type: integer
+--                   description: Total number of flows (may be limited by 'limit' parameter)
+--         FlowInfo:
+--           type: object
+--           properties:
+--             srv.ip:
+--               type: string
+--             cli.ip:
+--               type: string
+--             srv.port:
+--               type: integer
+--             cli.port:
+--               type: integer
+--             proto.ndpi_id:
+--               type: integer
+--             proto.ndpi:
+--               type: string
+--             bytes:
+--               type: integer
+--             cli2srv.throughput_bps:
+--               type: number
+--               format: float
+--             srv2cli.throughput_bps:
+--               type: number
+--               format: float
+--             cli2srv.throughput_pps:
+--               type: number
+--               format: float
+--             srv2cli.throughput_pps:
+--               type: number
+--               format: float
+--             cli2srv.tcp_flags:
+--               type: object
+--               description: TCP flags for client-to-server direction (TCP only)
+--             srv2cli.tcp_flags:
+--               type: object
+--               description: TCP flags for server-to-client direction (TCP only)
+--             tcp_established:
+--               type: boolean
+--               description: TCP connection established state (TCP only)
+--         ProtocolThroughput:
+--           type: object
+--           properties:
+--             cli2srv:
+--               type: object
+--               properties:
+--                 throughput_bps:
+--                   type: number
+--                   format: float
+--                 throughput_pps:
+--                   type: number
+--                   format: float
+--             srv2cli:
+--               type: object
+--               properties:
+--                 throughput_bps:
+--                   type: number
+--                   format: float
+--                 throughput_pps:
+--                   type: number
+--                   format: float
+--         ErrorResponse:
+--           type: object
+--           properties:
+--             error:
+--               type: object
+--               properties:
+--                 code:
+--                   type: integer
+--                 message:
+--                   type: string
+--                 details:
+--                   type: string
+--                 timestamp:
+--                   type: integer
+--                   format: int64
 
-local ifid = _GET["ifid"]
-local host_info = url2hostinfo(_GET)
+-- Initialize response variables
+local rc = rest_utils.consts.success.ok -- HTTP 200 OK response code
+local res = {} -- Response data container
 
--- whether to return host statistics: on by default
-local host_stats           = _GET["host_stats"]
+-- Parse input parameters from HTTP GET request
+local ifid = _GET["ifid"] -- Interface ID (required)
+local host_info = url2hostinfo(_GET) -- Parse host IP and optional VLAN from request
 
--- whether to return statistics regarding host flows: off by default
-local host_stats_flows     = _GET["host_stats_flows"]
-local host_stats_flows_num = _GET["limit"]
+-- Parse optional parameters with their default behaviors
+local host_stats = _GET["host_stats"] -- Control inclusion of host statistics (default: include)
+local host_stats_flows = _GET["host_stats_flows"] -- Control inclusion of flow statistics (default: exclude)
+local host_stats_flows_num = _GET["limit"] -- Maximum number of flows to return (when flows enabled)
 
+-- ============================================================================
+-- Input Validation Section
+-- ============================================================================
+
+-- Validate interface ID parameter
 if isEmptyString(ifid) then
+   -- Return HTTP 400 Bad Request: Missing or empty interface ID
    rest_utils.answer(rest_utils.consts.err.invalid_interface)
    return
 end
 
+-- Validate host IP address parameter
 if isEmptyString(host_info["host"]) then
+   -- Return HTTP 400 Bad Request: Missing or empty host address
    rest_utils.answer(rest_utils.consts.err.invalid_args)
    return
 end
 
+-- ============================================================================
+-- Host Data Retrieval Section
+-- ============================================================================
+
+-- Select the specified network interface for subsequent operations
 interface.select(ifid)
 
+-- Retrieve host information from ntopng monitoring engine
+-- Parameters: host IP address, VLAN ID (optional, defaults to 0)
 local host = interface.getHostInfo(host_info["host"], host_info["vlan"])
 
+-- Verify host exists on the selected interface
 if not host then
+   -- Return HTTP 404 Not Found: Host not present on interface
    rest_utils.answer(rest_utils.consts.err.not_found)
    return
 end
 
+-- ============================================================================
+-- Helper Function: Protocol Throughput Aggregation
+-- ============================================================================
+
+--- Aggregates flow throughput data by protocol for analysis
+-- This function processes an array of flow records and calculates total
+-- throughput (bps and pps) for each detected protocol, separated by
+-- traffic direction (client-to-server and server-to-client).
+--
+-- @function flows2protocolthpt
+-- @local
+-- @param flows table - Array of flow objects containing throughput data
+-- @return table - Nested table structure with protocol throughput statistics
+-- 
+-- @usage
+-- local throughput_stats = flows2protocolthpt(flows)
+-- print(throughput_stats["HTTP"]["cli2srv"]["throughput_bps"])
+--
+-- @note
+-- - Only flows with valid nDPI protocol classification are processed
+-- - Throughput values are summed across all matching flows
+-- - Structure supports easy charting and protocol analysis
 local function flows2protocolthpt(flows)
-   local protocol_thpt = {}
+   local protocol_thpt = {} -- Initialize empty throughput statistics table
+
+   -- Iterate through all provided flows
    for _, flow in pairs(flows) do
       local proto_ndpi = ""
+
+      -- Skip flows without valid nDPI protocol classification
       if flow["proto.ndpi"] == nil or flow["proto.ndpi"] == "" then
-	 goto continue
+         goto continue -- Use Lua goto for early loop continuation
       else
-	 proto_ndpi = flow["proto.ndpi"]
+         proto_ndpi = flow["proto.ndpi"]
       end
 
+      -- Initialize protocol entry if this is the first flow for this protocol
       if protocol_thpt[proto_ndpi] == nil then
-	 protocol_thpt[proto_ndpi] =
-	    {["cli2srv"]={["throughput_bps"]=0, ["throughput_pps"]=0},
-	       ["srv2cli"]={["throughput_bps"]=0, ["throughput_pps"]=0}}
+         protocol_thpt[proto_ndpi] = {
+            ["cli2srv"] = {
+               ["throughput_bps"] = 0, -- Bits per second (client → server)
+               ["throughput_pps"] = 0 -- Packets per second (client → server)
+            },
+            ["srv2cli"] = {
+               ["throughput_bps"] = 0, -- Bits per second (server → client)
+               ["throughput_pps"] = 0 -- Packets per second (server → client)
+            }
+         }
       end
 
+      -- Aggregate throughput for both traffic directions
       for _, dir in pairs({"cli2srv", "srv2cli"}) do
-	 for _, dim in pairs({"bps", "pps"}) do
-	    protocol_thpt[proto_ndpi][dir]["throughput_"..dim] =
-	       protocol_thpt[proto_ndpi][dir]["throughput_"..dim] + flow[dir..".throughput_"..dim]
-	 end
+         for _, dim in pairs({"bps", "pps"}) do
+            -- Calculate aggregated throughput by summing individual flow values
+            protocol_thpt[proto_ndpi][dir]["throughput_" .. dim] = protocol_thpt[proto_ndpi][dir]["throughput_" .. dim] +
+                                                                      flow[dir .. ".throughput_" .. dim]
+         end
       end
-      ::continue::
+
+      ::continue:: -- Label for goto statement (flow skipping)
    end
+
    return protocol_thpt
 end
 
--- hosts stats are on by default, one must explicitly disable them
+-- ============================================================================
+-- Host Statistics Processing (Conditional)
+-- ============================================================================
+
+-- Process host statistics based on request parameter
+-- Default behavior: Include statistics unless explicitly disabled
 if not (host_stats == nil or host_stats == "" or host_stats == "true" or host_stats == "1") then
+   -- Client requested NO host statistics - return empty host object
    host = {}
 end
 
--- host flow stats are off by default and must be explicitly enabled
+-- ============================================================================
+-- Flow Statistics Processing (Conditional)
+-- ============================================================================
+
+-- Process flow statistics if explicitly requested by client
 if host_stats_flows ~= nil and host_stats_flows ~= "" then
+   -- Determine maximum number of flows to retrieve
    if host_stats_flows_num == nil or tonumber(host_stats_flows_num) == nil then
-      -- default: do not limit the number of flows
+      -- Default: Retrieve up to 99999 flows (effectively all flows)
       host_stats_flows_num = 99999
    else
-      -- ... unless otherwise specified
+      -- Use client-specified limit, converted to number
       host_stats_flows_num = tonumber(host_stats_flows_num)
    end
 
+   -- Initialize total flow count (note: currently not populated in this implementation)
    local total = 0
 
-   local pageinfo = {["sortColumn"]="column_bytes", ["a2zSortOrder"]=false,
-      ["maxHits"]=host_stats_flows_num, ["toSkip"]=0, ["detailedResults"]=true}
+   -- Configure flow retrieval parameters for pagination and sorting
+   local pageinfo = {
+      ["sortColumn"] = "column_bytes", -- Sort by total bytes transferred
+      ["a2zSortOrder"] = false, -- Descending order (largest flows first)
+      ["maxHits"] = host_stats_flows_num, -- Maximum number of flows to retrieve
+      ["toSkip"] = 0, -- Start from first flow (no skipping)
+      ["detailedResults"] = true -- Include detailed flow information
+   }
 
-   --local flows = interface.getFlowsInfo(host_info["host"], nil, "column_bytes", host_stats_flows_num, 0, false)
+   -- Retrieve flows involving the specified host from ntopng engine
+   -- Uses pagination configuration for efficient data retrieval
    local flows = interface.getFlowsInfo(host_info["host"], pageinfo)
-   flows = flows["flows"]
+   flows = flows["flows"] -- Extract flow array from API response
+
+   -- Transform raw flow data into API response format
    for i, fl in ipairs(flows) do
+      -- Create simplified flow object with essential information
       flows[i] = {
-            ["srv.ip"] = fl["srv.ip"], ["cli.ip"] = fl["cli.ip"],
-            ["srv.port"] = fl["srv.port"], ["cli.port"] = fl["cli.port"],
-            ["proto.ndpi_id"] = fl["proto.ndpi_id"], ["proto.ndpi"] = fl["proto.ndpi"],
-            ["bytes"] = fl["bytes"],
-            ["cli2srv.throughput_bps"] = round(fl["throughput_cli2srv_bps"], 2),
-            ["srv2cli.throughput_bps"] = round(fl["throughput_srv2cli_bps"], 2),
-            ["cli2srv.throughput_pps"] = round(fl["throughput_cli2srv_pps"], 2),
-            ["srv2cli.throughput_pps"] = round(fl["throughput_srv2cli_pps"], 2),
+         -- Network endpoints
+         ["srv.ip"] = fl["srv.ip"], -- Server IP address
+         ["cli.ip"] = fl["cli.ip"], -- Client IP address
+         ["srv.port"] = fl["srv.port"], -- Server port number
+         ["cli.port"] = fl["cli.port"], -- Client port number
+
+         -- Protocol information
+         ["proto.ndpi_id"] = fl["proto.ndpi_id"], -- nDPI protocol numeric ID
+         ["proto.ndpi"] = fl["proto.ndpi"], -- nDPI protocol human-readable name
+
+         -- Volume metrics
+         ["bytes"] = fl["bytes"], -- Total bytes transferred in this flow
+
+         -- Throughput metrics (rounded to 2 decimal places for readability)
+         ["cli2srv.throughput_bps"] = round(fl["throughput_cli2srv_bps"], 2), -- Client→server bits/sec
+         ["srv2cli.throughput_bps"] = round(fl["throughput_srv2cli_bps"], 2), -- Server→client bits/sec
+         ["cli2srv.throughput_pps"] = round(fl["throughput_cli2srv_pps"], 2), -- Client→server packets/sec
+         ["srv2cli.throughput_pps"] = round(fl["throughput_srv2cli_pps"], 2) -- Server→client packets/sec
       }
 
+      -- Add TCP-specific information for TCP protocol flows
       if fl["proto.l4"] == "TCP" then
+         -- Convert TCP flags bitmask to human-readable table
          flows[i]["cli2srv.tcp_flags"] = TCPFlags2table(fl["cli2srv.tcp_flags"])
          flows[i]["srv2cli.tcp_flags"] = TCPFlags2table(fl["srv2cli.tcp_flags"])
-         flows[i]["tcp_established"]   = fl["tcp_established"]
+
+         -- TCP connection state
+         flows[i]["tcp_established"] = fl["tcp_established"] -- Boolean: connection fully established
       end
    end
 
+   -- Add aggregated protocol throughput statistics to host data
    host["ndpiThroughputStats"] = flows2protocolthpt(flows)
+
+   -- Add processed flow data to response
    host["flows"] = flows
-   host["flows_count"] = total
+   host["flows_count"] = total -- Note: Currently not populated, could be enhanced
 end
 
+-- ============================================================================
+-- Response Preparation and Logging
+-- ============================================================================
+
+-- Set final response data
 res = host
 
+-- Log API call for auditing and analytics
+-- Parameters: event type, array of relevant identifiers
 tracker.log("host_get_json", {host_info["host"], host_info["vlan"]})
 
+-- Send HTTP response with appropriate status code and JSON body
 rest_utils.answer(rc, res)
 
+-- ============================================================================
+-- End of API Implementation
+-- ============================================================================