René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Callback-Based Response Retrieval","articleBody":"One of the limitation in `lua-https` is that it's not possible for application to create download progress bars on it (if the `Content-Length` header is available). This is because `https.request` will wait until all the response data is retrieved.\r\n\r\nMy proposal is to add optional 3rd and 4th parameter `callback` and `context`. Callback is defined as these fields:\r\n```lua\r\nlocal callback = {\r\n    -- `context` in here means user-supplied data (4th-parameter), which can be anything.\r\n    response = function(context, status, headers)\r\n        -- Called when HTTP status code and headers has been retrieved. Called once.\r\n        -- `status` is HTTP status code\r\n        -- `headers` is HTTP headers in **all lowercase** for the keys.\r\n    end,\r\n    body = function(context, data)\r\n        -- Called when new HTTP body data arrives. Called multiple times as new data arrives.\r\n        -- `data` is response data as Lua string.\r\n        -- Return \"falsy\" value and additional error message (default is \"aborted\") to abort the request\r\n        return true -- success\r\n        return false, \"aborted\" -- failure\r\n    end,\r\n    complete = function(context, err)\r\n        -- Called when data has been transferred, or an error occurs.\r\n        -- `err` will be the error message, or `nil` if everything worked as intended.\r\n    end,\r\n}\r\n```\r\n\r\nExample usage:\r\n```lua\r\nlocal data = {current = 0, length = 0}\r\n\r\nhttps.request(\"https://love2d.org\", {}, {\r\n    -- `context` in here means user-supplied data (4th-parameter), which can be anything.\r\n    response = function(context, status, headers)\r\n        print(\"HTTP status code\", status)\r\n        if headers[\"content-length\"] then\r\n            context.length = tonumber(headers[\"content-length\"]) or 0\r\n        end\r\n    end,\r\n    body = function(context, data)\r\n        context.current = context.current + #data\r\n        if context.length \u003e 0 then\r\n            print(string.format(\"Received data %d bytes (%.2f)\", #data, context.current * 100 / context.length))\r\n        else\r\n            print(string.format(\"Received data %d bytes\", #data))\r\n        end\r\n    end,\r\n    complete = function(context, err)\r\n        if err then\r\n            print(\"Download error\", err)\r\n        else\r\n            print(\"Download completed!\")\r\n        end\r\n    end,\r\n}, data)\r\n```\r\n\r\nAs an additional feature/requirement, the `callback` table can be a class object (not instance) by retrieving the function list using Lua C function that invokes metamethod and the `context` can be the class instance itself such that when a class is declared like this:\r\n\r\n```lua\r\nlocal MyDownloader = class \"MyDownloader\"\r\n\r\nfunction MyDownloader:response(status, headers)\r\nend\r\n\r\nfunction MyDownloader:body(data)\r\n    return true\r\nend\r\n\r\nfunction MyDownloader:complete(err)\r\nend\r\n```\r\n\r\nDoing something like this simply works and calls the appropriate functions.\r\n\r\n```lua\r\nlocal dlinstance = MyDownloader() -- new class instance\r\nhttps.request(\"https://love2d.org\", {}, MyDownloader, dlinstance)\r\n```\r\n\r\nThe return value of `https.request` when using this variant would be questionable.\r\n* Returning the status code, body, and the headers will preserve backward compatibility, but at same time make things redundant (the library has to keep everything until the function returns instead of discarding them).\r\n* Returning only `true` or `false` + error message (`assert`-compatible style) means less redundancy, but breaks backward compatibility.\r\n\r\nI probably can do this, but the question becomes \"should this is be done?\" and/or \"is this valid usecase to justify the feature addition?\".","author":{"url":"https://github.com/MikuAuahDark","@type":"Person","name":"MikuAuahDark"},"datePublished":"2023-07-02T05:02:17.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":9},"url":"https://github.com/23/lua-https/issues/23"}