{"id":24818674,"url":"https://github.com/biril/http-util","last_synced_at":"2025-03-25T19:34:24.862Z","repository":{"id":57268413,"uuid":"11032600","full_name":"biril/http-util","owner":"biril","description":"Miscellaneous HTTP gimmicks","archived":false,"fork":false,"pushed_at":"2021-10-04T19:46:48.000Z","size":470,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-16T09:03:14.036Z","etag":null,"topics":["http","http-client","nodejs","wip"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/biril.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}},"created_at":"2013-06-28T17:14:57.000Z","updated_at":"2021-10-04T19:46:51.000Z","dependencies_parsed_at":"2022-09-02T05:41:05.560Z","dependency_job_id":null,"html_url":"https://github.com/biril/http-util","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fhttp-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fhttp-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fhttp-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fhttp-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biril","download_url":"https://codeload.github.com/biril/http-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245401332,"owners_count":20609166,"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":["http","http-client","nodejs","wip"],"created_at":"2025-01-30T17:37:19.307Z","updated_at":"2025-03-25T19:34:24.835Z","avatar_url":"https://github.com/biril.png","language":"JavaScript","readme":"HTTP Util\n=========\n\n[![Build Status](https://travis-ci.org/biril/http-util.png)](https://travis-ci.org/biril/http-util)\n[![NPM version](https://badge.fury.io/js/http-util.png)](http://badge.fury.io/js/http-util)\n\n\nAuthor's HTTP/S toolbox for Node.js. A compact collection of helpers especially applicable to\nstreaming, proxying, etc. Evolved from (and meant as a DRY replacement for) a number of common Node\npatterns. Currently focused on observability rather than performance.\n\n\nSet up\n------\n\n`git clone git://github.com/biril/http-util` or `npm install http-util` and `require`:\n\n```javascript\nvar httpUtil = require(\"http-util\");\nconsole.log(\"HTTP Util version: \" + httpUtil.version);\n```\n\n\nReference\n---------\n\nThe module's public API consists primarily of the `request` and `forward` methods which are\ndescribed here. An [annotated version](http://biril.github.io/http-util/) of the source is also\nmaintained as a complete reference.\n\n### request (url, rspOrStr[, opts]) → http.ClientRequest\n\nMake a request to some given host (the 'origin-server') and write received data into given\n`rspOrStr` - a `stream.Writable` or `http.ServerResponse`.\n\nThe `url` parameter is the _absolute_ URL of the resource to be requested. This may be a plain\n string or a URL object.\n\nThe `opts` parameter indicates further options. None of these is mandatory as they all default to\n sane values. [Note that in the following, 'response' does _not_ refer to the given `rspOrStr` but\n rather at the response received from the origin-server. This isn't accessible to API consumers so\n they need not be concerned with it. It nevertheless referred to, for clarification purposes. A\n request argument passed as `rspOrStr` will always be refered to as 'request-from-client'.]\n\n* `method`: Request method - an HTTP verb. 'GET' by default\n* `headers`: A hash of request headers. This may empty as 'host' (the only mandatory header\n    in HTTP/1.1) will be derived from given `url` if absent. Special headers that should be\n    noted are described in\n    [Node docs](http://nodejs.org/api/http.html#http_http_request_options_callback).\n* `maxContentLength`: The maximum allowed length for the received content. Lengthier responses will\n    be truncated. Optional (\u0026 experimental) - no max by default.\n* `followRedirects`: Indicates whether redirects should be silently followed, up until the request\n    reaches the origin-server (instead of interpreting the first redirect as a response-to-client).\n    Enabling this will buffer the request's content so that it may be resent on subsequent,\n    post-redirect requests. (This should especially be noted in cases where the request carries\n    sizable content.) False by default.\n* `onResponse`: Invoked, only once, when a response is first received. It will be passed the\n    response's status-code and headers. In the case where `rspOrStr` is an `http.ServerResponse`,\n    the caller may modify the received headers or inject new ones prior to them being written\n* `onResponseContent`: Invoked, only once, either when response content is first received or, if\n    there's no content for the response, when the response ends. Note that the handler is invoked\n    *before* the content is written to given stream / response-to-client. The received data chunk\n    (if there is one involved) is passed to the handler.\n* `onClose`: Invoked when the underlying connection to the origin-server is terminated before the\n    response ends or is able to flush. The caller may choose to abort the request in case it hasn't\n    already ended.\n* `onError`: Invoked in the event of a response-related error. The caller may choose to abort the\n    request in case it hasn't already ended. Note that the caller should primarily listen for errors\n    on the returned `http.ClientRequest` object.\n\nReturns the request made - an `http.ClientRequest`. This is in line with Node's\n [http.request](http://nodejs.org/api/http.html#http_http_request_options_callback): The request\n object may be used to push content to the origin-server, for example as part of a POST. The caller\n should always `end()` it (whether it writes any content to the body or not). In the event of an\n error during the request (be that with DNS resolution, TCP level errors, or actual HTTP parse\n errors) it will emit an 'error' event which the caller is expected to handle.\n\n\n### forward (request, response[, opts])\n\nForward a client request (`http.IncomingMessage`) to indicated server (the 'origin-server') and\n write received data into given response (`http.ServerResponse`). Particularly applicable in\n proxying scenarios\n\nThe `opts` parameter includes all options applicable to the request method with the (nonmandatory)\n addition of a `url` option:\n\n* In absense of this, requests will be forwarded to the original URL, i.e. `request.url`. Suitable\n   for authoring a forward proxy.\n* If `opts.url` is present, the request's original URL will be overriden, effectively forwarding to\n   a different host. This will also force an appropriately modified 'host' header derived from the\n   given URL. The caller may enforce a _specific_ 'host' by use of `opts.headers`. This method of\n   forwarding is suited to authoring a reverse proxy.\n\nIt should be noted that in the case of `forward`, the headers provided by use of `opts.headers` act\n as overrides. That is to say, the forwarded request will include _all_ of the original request's\n headers, either extended or overriden by those present in `opts.headers`. \n\n\nExamples\n--------\n\n\n### Forward proxy\n\n```javascript\nvar http = require(\"http\"),\n    httpUtil = require(\"http-util\");\n\nhttp.createServer(function (req, rsp) {\n    httpUtil.forward(req, rsp);\n}).listen(8080);\n```\n\n\n### Forward proxy with custom logic\n\nFake Googlebot:\n\n```javascript\nvar http = require(\"http\"),\n    httpUtil = require(\"http-util\");\n\nhttp.createServer(function (req, rsp) {\n    httpUtil.forward(req, rsp, {\n        headers: {\n        \t\"user-agent\": \"Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)\"\n        }\n    });\n}).listen(8080);\n```\n\nDisallow inferior search engines:\n\n```javascript\nvar http = require(\"http\"),\n\tparseUrl = require(\"url\").parse,\n    httpUtil = require(\"http-util\");\n\nhttp.createServer(function (req, rsp) {\n    httpUtil.forward(req, rsp, {\n        url: req.url.replace(\"bing\", \"google\"),\n        onResponse: function (statusCode, headers) {\n            headers[\"friendly-tip\"] = \"use google\";\n        }\n    });\n}).listen(8080);\n```\n\n\n### Reverse proxy\n\n// TODO\n\n\n### Fetching a resource\n\nDownload google's front-page HTML. Note the necessary `followRedirects` option.\n\n```javascript\nvar httpUtil = require(\"http-util\"),\n    file = require(\"fs\").createWriteStream(__dirname + \"/google.html\", { flags: \"w\" });\n\nhttpUtil.request(\"http://google.com\", file, {\n    followRedirects: true\n}).end();\n```\n\n\nTesting\n-------\n\n`make test` or `npm test`.\n\n\nLicense\n-------\n\nLicensed and freely distributed under the MIT License (LICENSE.txt).\n\nCopyright (c) 2012-2016 Alex Lambiris\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiril%2Fhttp-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiril%2Fhttp-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiril%2Fhttp-util/lists"}