{"id":19134057,"url":"https://github.com/umbrellio/ezclient","last_synced_at":"2025-07-24T10:39:41.561Z","repository":{"id":56845320,"uuid":"121535436","full_name":"umbrellio/ezclient","owner":"umbrellio","description":"An HTTP gem wrapper for easy persistent connections and more.","archived":false,"fork":false,"pushed_at":"2025-07-13T19:51:55.000Z","size":269,"stargazers_count":12,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-07-13T21:24:31.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/umbrellio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-14T16:47:54.000Z","updated_at":"2025-05-15T13:12:32.000Z","dependencies_parsed_at":"2024-06-18T09:27:31.321Z","dependency_job_id":"7a3af160-3927-4f60-be83-690275a7934b","html_url":"https://github.com/umbrellio/ezclient","commit_stats":{"total_commits":66,"total_committers":5,"mean_commits":13.2,"dds":0.09090909090909094,"last_synced_commit":"3221ad6a9da32ee46f3e75e0645309f417ed65ba"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/umbrellio/ezclient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fezclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fezclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fezclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fezclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umbrellio","download_url":"https://codeload.github.com/umbrellio/ezclient/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umbrellio%2Fezclient/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265212019,"owners_count":23728509,"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":[],"created_at":"2024-11-09T06:25:15.577Z","updated_at":"2025-07-24T10:39:41.527Z","avatar_url":"https://github.com/umbrellio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EzClient   [![Gem Version](https://badge.fury.io/rb/ezclient.svg)](https://badge.fury.io/rb/ezclient) [![Build Status](https://travis-ci.org/umbrellio/ezclient.svg?branch=master)](https://travis-ci.org/umbrellio/ezclient) [![Coverage Status](https://coveralls.io/repos/github/umbrellio/ezclient/badge.svg?branch=master)](https://coveralls.io/github/umbrellio/ezclient?branch=master)\n\nEzClient is [HTTP gem](https://github.com/httprb/http) wrapper for easy persistent connections and more.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"ezclient\"\n```\n\n## Usage\n\n```ruby\nurl = \"http://example.com\"\n\nclient_options = { timeout: 10 }\nclient = EzClient.new(client_options) # =\u003e EzClient::Client object\n\nrequest_options = { params: { a: 1 } }\nrequest = client.request(:get, url, request_options) # =\u003e EzClient::Request object\n\n# Performs a GET request to https://example.com/?a=1\nresponse = request.perform # =\u003e EzClient::Response object\n\n# Same request but will raise EzClient::ResponseStatusError in case of 4xx or 5xx response code\nresponse = request.perform!\n\n# Alternatively, you can just do:\nresponse = client.perform!(:get, url, request_options) # =\u003e EzClient::Response object\n```\n\nValid client options are:\n\n- `api_auth` – arguments for `ApiAuth.sign!` (see https://github.com/mgomes/api_auth)\n- `basic_auth` – arguments for basic authentication (either a hash with `:user` and `:pass` keys or a two-element array)\n- `cookies` – a hash of cookies (or `HTTP::CookieJar` object) for requests\n- `headers` – a hash of headers for requests\n- `keep_alive` – timeout for persistent connection in seconds\n- `max_retries` – maximum number of retries in case `retry_exceptions` option is provided\n- `on_complete` – callback called on request completion\n- `on_error` – callback called on request exception\n- `on_retry` – callback called on request retry\n- `retry_exceptions` – an array of exception classes to retry\n- `ssl_context` – ssl context for requests (an `OpenSSL::SSL::SSLContext` instance)\n- `timeout` – timeout for requests in seconds or hash like `{ read: 5, write: 5, connect: 1 }`\n- `follow` – enable following redirects (`true` or hash with options – e.g. `{ max_hops: 1, strict: false}`)\n- `error_wrapper` – callback called on request exception, makes it possible to handle any error, default behavior: `raise error`\n\nAll these options are passed to each request made by this client but can be overriden on per-request basis.\n\nExtra per-request only options are:\n\n- `body` – raw request body\n- `form` – hash for urlencoded body\n- `json` – data for json (also adds `application/json` content-type header)\n- `metadata` – metadata for request (passed in callbacks)\n- `params` – becomes `query` for GET and `form` for other requests\n- `query` – hash for uri query\n\n## Persistent connections\n\nIf you provide `keep_alive` option to the client or particular request, the connection will be stored in the client and then\nreused for all following requests to the same origin within specified amount of time.\n\nNote that if you are using persistent connections, you shouldn't store your client in a variable that is accessable by different threads. See the example:\n\n```ruby\nmodule MyApp\n  # Bad: multiple threads will use the same socket\n  def self.bad_client\n    @ezclient ||= EzClient.new(keep_alive: 100)\n  end\n\n  # Good: each thread has it's own socket\n  def self.good_client\n    Thread.current[:ezclient] ||= EzClient.new(keep_alive: 100)\n  end\nend\n```\n\nAlose note that, as of now, EzClient will\nautomatically retry the request on any `HTTP::ConnectionError` exception in this case which may possibly result in two requests\nreceived by a server (see https://github.com/httprb/http/issues/459).\n\n## Callbacks and retrying\n\nYou can provide `on_complete`, `on_error` and `on_retry` callbacks like this:\n\n```ruby\non_complete = -\u003e (request, response, metadata) { ... }\non_error = -\u003e (request, error, metadata) { ... }\non_retry = -\u003e (request, error, metadata) { ... }\nerror_wrapper = -\u003e (request, error, metadata) { raise error }\n\nclient = EzClient.new(\n  on_complete: on_complete,\n  on_error: on_error,\n  on_retry: on_retry,\n  retry_exceptions: [StandardError],\n  max_retries: 2,\n  error_wrapper: error_wrapper\n)\n\nresponse = client.perform!(:get, url, metadata: :hello)\n```\n\nThe arguments passed into callbacks are:\n\n- `request` – an `EzClient::Request` instance\n- `response` – an `EzClient::Response` instance\n- `error` – an exception instance\n- `metadata` - the `metadata` option passed into a request\n\n## Request object\n\n```ruby\nrequest = client.request(:post, \"http://example.com\", json: { a: 1 }, timeout: 15)\n\nrequest.verb # =\u003e \"POST\"\nrequest.url # =\u003e \"http://example.com\"\nrequest.body # =\u003e '{\"a\": 1}'\nrequest.headers # =\u003e { \"Content-Type\" =\u003e \"application/json; charset=UTF-8\", ... }\nrequest.elapsed_seconds # =\u003e 0.08117745001072763\n```\n\n## Response object\n\n```ruby\nresponse = request.perform(...)\n\nresponse.body # =\u003e String\nresponse.headers # =\u003e Hash\nresponse.code # =\u003e Integer\n\nresponse.ok? # Returns if request was 2xx status\nresponse.redirect? # Returns if request was 3xx status\nresponse.client_error? # Returns if request was 4xx status\nresponse.server_error? # Returns if request was 5xx status\nresponse.error? # Returns if request was 4xx or 5xx status\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/umbrellio/ezclient.\n\n## License\n\nReleased under MIT License.\n\n## Authors\n\nCreated by Yuri Smirnov.\n\n\u003ca href=\"https://github.com/umbrellio/\"\u003e\n\u003cimg style=\"float: left;\" src=\"https://umbrellio.github.io/Umbrellio/supported_by_umbrellio.svg\" alt=\"Supported by Umbrellio\" width=\"439\" height=\"72\"\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbrellio%2Fezclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumbrellio%2Fezclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumbrellio%2Fezclient/lists"}