{"id":13777550,"url":"https://github.com/thibaultcha/lua-resty-socket","last_synced_at":"2025-10-26T15:31:48.691Z","repository":{"id":54433219,"uuid":"51897293","full_name":"thibaultcha/lua-resty-socket","owner":"thibaultcha","description":"Automatic LuaSocket/cosockets compatibility module","archived":false,"fork":false,"pushed_at":"2023-02-08T20:37:11.000Z","size":48,"stargazers_count":36,"open_issues_count":4,"forks_count":21,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-04-14T20:01:55.039Z","etag":null,"topics":["lua-resty","luasocket","ngx-lua","openresty"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thibaultcha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-02-17T05:29:32.000Z","updated_at":"2023-10-31T18:22:56.000Z","dependencies_parsed_at":"2024-01-13T10:43:09.493Z","dependency_job_id":"f539d85b-c0b4-41de-b0f4-df91ddc6003f","html_url":"https://github.com/thibaultcha/lua-resty-socket","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-socket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-socket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-socket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibaultcha%2Flua-resty-socket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thibaultcha","download_url":"https://codeload.github.com/thibaultcha/lua-resty-socket/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245198659,"owners_count":20576410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua-resty","luasocket","ngx-lua","openresty"],"created_at":"2024-08-03T18:00:45.187Z","updated_at":"2025-10-26T15:31:48.640Z","avatar_url":"https://github.com/thibaultcha.png","language":"Perl","funding_links":[],"categories":["Libraries","Perl"],"sub_categories":[],"readme":"# lua-resty-socket\n\n![Module Version][badge-version-image]\n[![Build Status][badge-travis-image]][badge-travis-url]\n\ncosocket/LuaSocket automatic compatibility module for lua-resty modules wanting\nto be compatible with plain Lua or OpenResty's `init` context.\n\nThe use case for this library is: you are developing a lua-resty module relying\non cosockets, but you want it to also be usable in OpenResty's `init` context\nor even in plain Lua. This module aims at always providing your library with\nsockets that will be compatible in the current context, saving you time and\neffort, and extending LuaSocket's API to match that of cosockets, allowing you\nto always write your code as if you were in a cosocket-compatible OpenResty\ncontext.\n\n### Table of Contents\n\n* [Features](#features)\n* [Motivation](#motivation)\n* [Libraries using it](#libraries-using-it)\n* [Important note](#important-note)\n* [Usage](#usage)\n* [Requirements](#requirements)\n* [Installation](#installation)\n* [License](#license)\n\n### Features\n\n* Allows your lua-resty modules to automatically use cosockets/LuaSocket\n* Provides `sslhandshake` proxy when using LuaSocket, with a dependency on\n  LuaSec\n* Does not get blocked to using LuaSocket in further contexts if loaded in the\n  ngx_lua `init` (easy mistake to make)\n* Memoizes underlying socket methods for performance\n* Outputs a warning log for your users when spawning a socket using LuaSocket\n  while in OpenResty\n\n[Back to TOC](#table-of-contents)\n\n### Motivation\n\nThe aim of this module is to provide an automatic fallback to LuaSocket when\n[ngx_lua]'s cosockets are not available. That is:\n- When not used in ngx_lua\n- In ngx_lua contexts where cosockets are not supported (`init`, `init_worker`,\netc...)\n\nWhen falling back to LuaSocket, it provides you with shims for cosocket-only\nfunctions such as `getreusedtimes`, `setkeepalive` etc...\n\nIt comes handy when one is developing a module/library that aims at being\neither compatible with both ngx_lua **and** plain Lua, **or** in ngx_lua\ncontexts such as `init`.\n\n[Back to TOC](#table-of-contents)\n\n### Libraries using it\n\nHere are some concrete examples uses of this module. You can see how we only\nwrite code as if we were constantly in an cosocket-compatible OpenResty\ncontext, which greatly simplifies our work and provides out of the box plain\nLua compatibility.\n\n* [lua-cassandra](https://github.com/thibaultcha/lua-cassandra): see how the\n  [cassandra](https://github.com/thibaultcha/lua-cassandra/blob/master/lib/cassandra/init.lua)\n  module is compatible in both OpenResty and plain Lua with no efforts or\n  special code paths distinguishing cosockets and LuaSocket.\n\n[Back to TOC](#table-of-contents)\n\n### Important note\n\nThe use of LuaSocket inside ngx_lua is **very strongly** discouraged due to its\nblocking nature. However, it is fine to use it in the `init` context where\nblocking is not considered harmful.\n\nIn the future, only the `init` phase will allow falling back to LuaSocket.\n\nIt currently only support TCP sockets.\n\n[Back to TOC](#table-of-contents)\n\n## Usage\n\nAll of the available functions follow the same prototype as the cosocket API,\nallowing this example to run in any ngx_lua context or outside ngx_lua\naltogether:\n```lua\nlocal socket = require 'resty.socket'\nlocal sock = socket.tcp()\n\ngetmetatable(sock) == socket.luasocket_mt ---\u003e true/false depending on underlying socket\n\nsock:settimeout(1000) ---\u003e 1000ms translated to 1s if LuaSocket\n\nsock:getreusedtimes(...) ---\u003e 0 if LuaSocket\n\nsock:setkeepalive(...) ---\u003e calls close() if LuaSocket\n\nsock:sslhandshake(...) ---\u003e LuaSec dependency if LuaSocket\n```\n\nAs such, one can write a module relying on TCP sockets such as:\n```lua\nlocal socket = require 'resty.socket'\n\nlocal _M = {}\n\nfunction _M.new()\n  local sock = socket.tcp() -- similar to ngx.socket.tcp()\n\n  return setmetatable({\n    sock = sock\n  }, {__index = _M})\nend\n\nfunction _M:connect(host, port)\n  local ok, err = self.sock:connect(host, port)\n  if not ok then\n    return nil, err\n  end\n\n  local times, err = self.sock:getreusedtimes() -- cosocket API\n  if not times then\n    return nil, err\n  elseif times == 0 then\n    -- handle connection\n  end\nend\n\nreturn _M\n```\n\nThe user of such a module could use it in contexts with cosocket support, or\nin the `init` phase of ngx_lua, with little effort from the developer.\n\n[Back to TOC](#table-of-contents)\n\n### Requirements\n\n**As long as sockets are created in contexts with support for cosockets, this\nmodule will never require LuaSocket nor LuaSec.**\n\n- LuaSocket (only if sockets are created where cosockets don't exist)\n- LuaSec (only if the fallbacked socket attempts to perform an SSL handshake)\n\n[Back to TOC](#table-of-contents)\n\n### Installation\n\nThis module can either be copied in a lua-resty library, allowing one to\nmodify the list of contexts allowing fallback.\n\nIt can also be installed via LuaRocks:\n\n```shell\n$ luarocks install lua-resty-socket\n```\n\n[Back to TOC](#table-of-contents)\n\n### License\n\nWork licensed under the MIT License.\n\n[Back to TOC](#table-of-contents)\n\n[ngx_lua]: https://github.com/openresty/lua-nginx-module\n\n[badge-travis-url]: https://travis-ci.org/thibaultcha/lua-resty-socket\n[badge-travis-image]: https://travis-ci.org/thibaultcha/lua-resty-socket.svg?branch=master\n\n[badge-version-image]: https://img.shields.io/badge/version-1.0.0-blue.svg?style=flat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-resty-socket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthibaultcha%2Flua-resty-socket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibaultcha%2Flua-resty-socket/lists"}