{ "content": [ { "type": "text", "text": "# HTTP::Tiny (info)\n\n## NAME\n\nHTTP::Tiny - A small, simple, correct HTTP/1.1 client\n\n## SYNOPSIS\n\nuse HTTP::Tiny;\nmy $response = HTTP::Tiny->new->get('http://example.com/');\ndie \"Failed!\\n\" unless $response->{success};\nprint \"$response->{status} $response->{reason}\\n\";\nwhile (my ($k, $v) = each %{$response->{headers}}) {\nfor (ref $v eq 'ARRAY' ? @$v : $v) {\nprint \"$k: $\\n\";\n}\n}\nprint $response->{content} if length $response->{content};\n\n## DESCRIPTION\n\nThis is a very simple HTTP/1.1 client, designed for doing simple\nrequests without the overhead of a large framework like LWP::UserAgent.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **SSL SUPPORT**\n- **PROXY SUPPORT**\n- **LIMITATIONS**\n- **SEE ALSO**\n- **SUPPORT**\n- **AUTHORS**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "HTTP::Tiny", "section": "", "mode": "info", "summary": "HTTP::Tiny - A small, simple, correct HTTP/1.1 client", "synopsis": "use HTTP::Tiny;\nmy $response = HTTP::Tiny->new->get('http://example.com/');\ndie \"Failed!\\n\" unless $response->{success};\nprint \"$response->{status} $response->{reason}\\n\";\nwhile (my ($k, $v) = each %{$response->{headers}}) {\nfor (ref $v eq 'ARRAY' ? @$v : $v) {\nprint \"$k: $\\n\";\n}\n}\nprint $response->{content} if length $response->{content};", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 16, "subsections": [] }, { "name": "DESCRIPTION", "lines": 12, "subsections": [] }, { "name": "METHODS", "lines": 267, "subsections": [] }, { "name": "SSL SUPPORT", "lines": 76, "subsections": [] }, { "name": "PROXY SUPPORT", "lines": 30, "subsections": [] }, { "name": "LIMITATIONS", "lines": 54, "subsections": [] }, { "name": "SEE ALSO", "lines": 19, "subsections": [] }, { "name": "SUPPORT", "lines": 13, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 74, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "HTTP::Tiny - A small, simple, correct HTTP/1.1 client\n", "subsections": [] }, "VERSION": { "content": "version 0.076\n", "subsections": [] }, "SYNOPSIS": { "content": "use HTTP::Tiny;\n\nmy $response = HTTP::Tiny->new->get('http://example.com/');\n\ndie \"Failed!\\n\" unless $response->{success};\n\nprint \"$response->{status} $response->{reason}\\n\";\n\nwhile (my ($k, $v) = each %{$response->{headers}}) {\nfor (ref $v eq 'ARRAY' ? @$v : $v) {\nprint \"$k: $\\n\";\n}\n}\n\nprint $response->{content} if length $response->{content};\n", "subsections": [] }, "DESCRIPTION": { "content": "This is a very simple HTTP/1.1 client, designed for doing simple\nrequests without the overhead of a large framework like LWP::UserAgent.\n\nIt is more correct and more complete than HTTP::Lite. It supports\nproxies and redirection. It also correctly resumes after EINTR.\n\nIf IO::Socket::IP 0.25 or later is installed, HTTP::Tiny will use it\ninstead of IO::Socket::INET for transparent support for both IPv4 and\nIPv6.\n\nCookie support requires HTTP::CookieJar or an equivalent class.\n", "subsections": [] }, "METHODS": { "content": "new\n$http = HTTP::Tiny->new( %attributes );\n\nThis constructor returns a new HTTP::Tiny object. Valid attributes\ninclude:\n\no \"agent\" -- A user-agent string (defaults to 'HTTP-Tiny/$VERSION').\nIf \"agent\" -- ends in a space character, the default user-agent\nstring is appended.\n\no \"cookiejar\" -- An instance of HTTP::CookieJar -- or equivalent\nclass that supports the \"add\" and \"cookieheader\" methods\n\no \"defaultheaders\" -- A hashref of default headers to apply to\nrequests\n\no \"localaddress\" -- The local IP address to bind to\n\no \"keepalive\" -- Whether to reuse the last connection (if for the\nsame scheme, host and port) (defaults to 1)\n\no \"maxredirect\" -- Maximum number of redirects allowed (defaults to\n5)\n\no \"maxsize\" -- Maximum response size in bytes (only when not using a\ndata callback). If defined, responses larger than this will return\nan exception.\n\no \"httpproxy\" -- URL of a proxy server to use for HTTP connections\n(default is $ENV{httpproxy} -- if set)\n\no \"httpsproxy\" -- URL of a proxy server to use for HTTPS connections\n(default is $ENV{httpsproxy} -- if set)\n\no \"proxy\" -- URL of a generic proxy server for both HTTP and HTTPS\nconnections (default is $ENV{allproxy} -- if set)\n\no \"noproxy\" -- List of domain suffixes that should not be proxied.\nMust be a comma-separated string or an array reference. (default is\n$ENV{noproxy} --)\n\no \"timeout\" -- Request timeout in seconds (default is 60) If a socket\nopen, read or write takes longer than the timeout, an exception is\nthrown.\n\no \"verifySSL\" -- A boolean that indicates whether to validate the\nSSL certificate of an \"https\" -- connection (default is false)\n\no \"SSLoptions\" -- A hashref of \"SSL*\" -- options to pass through to\nIO::Socket::SSL\n\nPassing an explicit \"undef\" for \"proxy\", \"httpproxy\" or \"httpsproxy\"\nwill prevent getting the corresponding proxies from the environment.\n\nExceptions from \"maxsize\", \"timeout\" or other errors will result in a\npseudo-HTTP status code of 599 and a reason of \"Internal Exception\".\nThe content field in the response will contain the text of the\nexception.\n\nThe \"keepalive\" parameter enables a persistent connection, but only to\na single destination scheme, host and port. Also, if any connection-\nrelevant attributes are modified, or if the process ID or thread ID\nchange, the persistent connection will be dropped. If you want\npersistent connections across multiple destinations, use multiple\nHTTP::Tiny objects.\n\nSee \"SSL SUPPORT\" for more on the \"verifySSL\" and \"SSLoptions\"\nattributes.\n\nget|head|put|post|delete\n$response = $http->get($url);\n$response = $http->get($url, \\%options);\n$response = $http->head($url);\n\nThese methods are shorthand for calling \"request()\" for the given\nmethod. The URL must have unsafe characters escaped and international\ndomain names encoded. See \"request()\" for valid options and a\ndescription of the response.\n\nThe \"success\" field of the response will be true if the status code is\n2XX.\n\npostform\n$response = $http->postform($url, $formdata);\n$response = $http->postform($url, $formdata, \\%options);\n\nThis method executes a \"POST\" request and sends the key/value pairs\nfrom a form data hash or array reference to the given URL with a\n\"content-type\" of \"application/x-www-form-urlencoded\". If data is\nprovided as an array reference, the order is preserved; if provided as\na hash reference, the terms are sorted on key and value for\nconsistency. See documentation for the \"wwwformurlencode\" method for\ndetails on the encoding.\n\nThe URL must have unsafe characters escaped and international domain\nnames encoded. See \"request()\" for valid options and a description of\nthe response. Any \"content-type\" header or content in the options\nhashref will be ignored.\n\nThe \"success\" field of the response will be true if the status code is\n2XX.\n\nmirror\n$response = $http->mirror($url, $file, \\%options)\nif ( $response->{success} ) {\nprint \"$file is up to date\\n\";\n}\n\nExecutes a \"GET\" request for the URL and saves the response body to the\nfile name provided. The URL must have unsafe characters escaped and\ninternational domain names encoded. If the file already exists, the\nrequest will include an \"If-Modified-Since\" header with the\nmodification timestamp of the file. You may specify a different\n\"If-Modified-Since\" header yourself in the \"$options->{headers}\" hash.\n\nThe \"success\" field of the response will be true if the status code is\n2XX or if the status code is 304 (unmodified).\n\nIf the file was modified and the server response includes a properly\nformatted \"Last-Modified\" header, the file modification time will be\nupdated accordingly.\n\nrequest\n$response = $http->request($method, $url);\n$response = $http->request($method, $url, \\%options);\n\nExecutes an HTTP request of the given method type ('GET', 'HEAD',\n'POST', 'PUT', etc.) on the given URL. The URL must have unsafe\ncharacters escaped and international domain names encoded.\n\nNOTE: Method names are case-sensitive per the HTTP/1.1 specification.\nDon't use \"get\" when you really want \"GET\". See LIMITATIONS for how\nthis applies to redirection.\n\nIf the URL includes a \"user:password\" stanza, they will be used for\nBasic-style authorization headers. (Authorization headers will not be\nincluded in a redirected request.) For example:\n\n$http->request('GET', 'http://Aladdin:open sesame@example.com/');\n\nIf the \"user:password\" stanza contains reserved characters, they must\nbe percent-escaped:\n\n$http->request('GET', 'http://john%40example.com:password@example.com/');\n\nA hashref of options may be appended to modify the request.\n\nValid options are:\n\no \"headers\" -- A hashref containing headers to include with the\nrequest. If the value for a header is an array reference, the\nheader will be output multiple times with each value in the array.\nThese headers over-write any default headers.\n\no \"content\" -- A scalar to include as the body of the request OR a\ncode reference that will be called iteratively to produce the body\nof the request\n\no \"trailercallback\" -- A code reference that will be called if it\nexists to provide a hashref of trailing headers (only used with\nchunked transfer-encoding)\n\no \"datacallback\" -- A code reference that will be called for each\nchunks of the response body received.\n\no \"peer\" -- Override host resolution and force all connections to go\nonly to a specific peer address, regardless of the URL of the\nrequest. This will include any redirections! This options should\nbe used with extreme caution (e.g. debugging or very special\ncircumstances). It can be given as either a scalar or a code\nreference that will receive the hostname and whose response will be\ntaken as the address.\n\nThe \"Host\" header is generated from the URL in accordance with RFC\n2616. It is a fatal error to specify \"Host\" in the \"headers\" option.\nOther headers may be ignored or overwritten if necessary for transport\ncompliance.\n\nIf the \"content\" option is a code reference, it will be called\niteratively to provide the content body of the request. It should\nreturn the empty string or undef when the iterator is exhausted.\n\nIf the \"content\" option is the empty string, no \"content-type\" or\n\"content-length\" headers will be generated.\n\nIf the \"datacallback\" option is provided, it will be called\niteratively until the entire response body is received. The first\nargument will be a string containing a chunk of the response body, the\nsecond argument will be the in-progress response hash reference, as\ndescribed below. (This allows customizing the action of the callback\nbased on the \"status\" or \"headers\" received prior to the content body.)\n\nThe \"request\" method returns a hashref containing the response. The\nhashref will have the following keys:\n\no \"success\" -- Boolean indicating whether the operation returned a\n2XX status code\n\no \"url\" -- URL that provided the response. This is the URL of the\nrequest unless there were redirections, in which case it is the\nlast URL queried in a redirection chain\n\no \"status\" -- The HTTP status code of the response\n\no \"reason\" -- The response phrase returned by the server\n\no \"content\" -- The body of the response. If the response does not\nhave any content or if a data callback is provided to consume the\nresponse body, this will be the empty string\n\no \"headers\" -- A hashref of header fields. All header field names\nwill be normalized to be lower case. If a header is repeated, the\nvalue will be an arrayref; it will otherwise be a scalar string\ncontaining the value\n\no \"protocol\" - If this field exists, it is the protocol of the\nresponse such as HTTP/1.0 or HTTP/1.1\n\no \"redirects\" If this field exists, it is an arrayref of response\nhash references from redirects in the same order that redirections\noccurred. If it does not exist, then no redirections occurred.\n\nOn an exception during the execution of the request, the \"status\" field\nwill contain 599, and the \"content\" field will contain the text of the\nexception.\n\nwwwformurlencode\n$params = $http->wwwformurlencode( $data );\n$response = $http->get(\"http://example.com/query?$params\");\n\nThis method converts the key/value pairs from a data hash or array\nreference into a \"x-www-form-urlencoded\" string. The keys and values\nfrom the data reference will be UTF-8 encoded and escaped per RFC 3986.\nIf a value is an array reference, the key will be repeated with each of\nthe values of the array reference. If data is provided as a hash\nreference, the key/value pairs in the resulting string will be sorted\nby key and value for consistent ordering.\n\ncanssl\n$ok = HTTP::Tiny->canssl;\n($ok, $why) = HTTP::Tiny->canssl;\n($ok, $why) = $http->canssl;\n\nIndicates if SSL support is available. When called as a class object,\nit checks for the correct version of Net::SSLeay and IO::Socket::SSL.\nWhen called as an object methods, if \"SSLverify\" is true or if\n\"SSLverifymode\" is set in \"SSLoptions\", it checks that a CA file is\navailable.\n\nIn scalar context, returns a boolean indicating if SSL is available.\nIn list context, returns the boolean and a (possibly multi-line) string\nof errors indicating why SSL isn't available.\n\nconnected\n$host = $http->connected;\n($host, $port) = $http->connected;\n\nIndicates if a connection to a peer is being kept alive, per the\n\"keepalive\" option.\n\nIn scalar context, returns the peer host and port, joined with a colon,\nor \"undef\" (if no peer is connected). In list context, returns the\npeer host and port or an empty list (if no peer is connected).\n\nNote: This method cannot reliably be used to discover whether the\nremote host has closed its end of the socket.\n", "subsections": [] }, "SSL SUPPORT": { "content": "Direct \"https\" connections are supported only if IO::Socket::SSL 1.56\nor greater and Net::SSLeay 1.49 or greater are installed. An exception\nwill be thrown if new enough versions of these modules are not\ninstalled or if the SSL encryption fails. You can also use\n\"HTTP::Tiny::canssl()\" utility function that returns boolean to see if\nthe required modules are installed.\n\nAn \"https\" connection may be made via an \"http\" proxy that supports the\nCONNECT command (i.e. RFC 2817). You may not proxy \"https\" via a proxy\nthat itself requires \"https\" to communicate.\n\nSSL provides two distinct capabilities:\n\no Encrypted communication channel\n\no Verification of server identity\n\nBy default, HTTP::Tiny does not verify server identity.\n\nServer identity verification is controversial and potentially tricky\nbecause it depends on a (usually paid) third-party Certificate\nAuthority (CA) trust model to validate a certificate as legitimate.\nThis discriminates against servers with self-signed certificates or\ncertificates signed by free, community-driven CA's such as CAcert.org\n.\n\nBy default, HTTP::Tiny does not make any assumptions about your trust\nmodel, threat level or risk tolerance. It just aims to give you an\nencrypted channel when you need one.\n\nSetting the \"verifySSL\" attribute to a true value will make HTTP::Tiny\nverify that an SSL connection has a valid SSL certificate corresponding\nto the host name of the connection and that the SSL certificate has\nbeen verified by a CA. Assuming you trust the CA, this will protect\nagainst a man-in-the-middle attack . If you are concerned about security, you should\nenable this option.\n\nCertificate verification requires a file containing trusted CA\ncertificates.\n\nIf the environment variable \"SSLCERTFILE\" is present, HTTP::Tiny will\ntry to find a CA certificate file in that location.\n\nIf the Mozilla::CA module is installed, HTTP::Tiny will use the CA file\nincluded with it as a source of trusted CA's. (This means you trust\nMozilla, the author of Mozilla::CA, the CPAN mirror where you got\nMozilla::CA, the toolchain used to install it, and your operating\nsystem security, right?)\n\nIf that module is not available, then HTTP::Tiny will search several\nsystem-specific default locations for a CA certificate file:\n\no /etc/ssl/certs/ca-certificates.crt\n\no /etc/pki/tls/certs/ca-bundle.crt\n\no /etc/ssl/ca-bundle.pem\n\nAn exception will be raised if \"verifySSL\" is true and no CA\ncertificate file is available.\n\nIf you desire complete control over SSL connections, the \"SSLoptions\"\nattribute lets you provide a hash reference that will be passed through\nto \"IO::Socket::SSL::startSSL()\", overriding any options set by\nHTTP::Tiny. For example, to provide your own trusted CA file:\n\nSSLoptions => {\nSSLcafile => $filepath,\n}\n\nThe \"SSLoptions\" attribute could also be used for such things as\nproviding a client certificate for authentication to a server or\ncontrolling the choice of cipher used for the SSL connection. See\nIO::Socket::SSL documentation for details.\n", "subsections": [] }, "PROXY SUPPORT": { "content": "HTTP::Tiny can proxy both \"http\" and \"https\" requests. Only Basic\nproxy authorization is supported and it must be provided as part of the\nproxy URL: \"http://user:pass@proxy.example.com/\".\n\nHTTP::Tiny supports the following proxy environment variables:\n\no httpproxy or HTTPPROXY\n\no httpsproxy or HTTPSPROXY\n\no allproxy or ALLPROXY\n\nIf the \"REQUESTMETHOD\" environment variable is set, then this might be\na CGI process and \"HTTPPROXY\" would be set from the \"Proxy:\" header,\nwhich is a security risk. If \"REQUESTMETHOD\" is set, \"HTTPPROXY\"\n(the upper case variant only) is ignored.\n\nTunnelling \"https\" over an \"http\" proxy using the CONNECT method is\nsupported. If your proxy uses \"https\" itself, you can not tunnel\n\"https\" over it.\n\nBe warned that proxying an \"https\" connection opens you to the risk of\na man-in-the-middle attack by the proxy server.\n\nThe \"noproxy\" environment variable is supported in the format of a\ncomma-separated list of domain extensions proxy should not be used for.\n\nProxy arguments passed to \"new\" will override their corresponding\nenvironment variables.\n", "subsections": [] }, "LIMITATIONS": { "content": "HTTP::Tiny is conditionally compliant with the HTTP/1.1 specifications\n:\n\no \"Message Syntax and Routing\" [RFC7230]\n\no \"Semantics and Content\" [RFC7231]\n\no \"Conditional Requests\" [RFC7232]\n\no \"Range Requests\" [RFC7233]\n\no \"Caching\" [RFC7234]\n\no \"Authentication\" [RFC7235]\n\nIt attempts to meet all \"MUST\" requirements of the specification, but\ndoes not implement all \"SHOULD\" requirements. (Note: it was developed\nagainst the earlier RFC 2616 specification and may not yet meet the\nrevised RFC 7230-7235 spec.)\n\nSome particular limitations of note include:\n\no HTTP::Tiny focuses on correct transport. Users are responsible for\nensuring that user-defined headers and content are compliant with\nthe HTTP/1.1 specification.\n\no Users must ensure that URLs are properly escaped for unsafe\ncharacters and that international domain names are properly encoded\nto ASCII. See URI::Escape, URI::punycode and Net::IDN::Encode.\n\no Redirection is very strict against the specification. Redirection\nis only automatic for response codes 301, 302, 307 and 308 if the\nrequest method is 'GET' or 'HEAD'. Response code 303 is always\nconverted into a 'GET' redirection, as mandated by the\nspecification. There is no automatic support for status 305 (\"Use\nproxy\") redirections.\n\no There is no provision for delaying a request body using an \"Expect\"\nheader. Unexpected \"1XX\" responses are silently ignored as per the\nspecification.\n\no Only 'chunked' \"Transfer-Encoding\" is supported.\n\no There is no support for a Request-URI of '*' for the 'OPTIONS'\nrequest.\n\no Headers mentioned in the RFCs and some other, well-known headers\nare generated with their canonical case. Other headers are sent in\nthe case provided by the user. Except for control headers (which\nare sent first), headers are sent in arbitrary order.\n\nDespite the limitations listed above, HTTP::Tiny is considered feature-\ncomplete. New feature requests should be directed to HTTP::Tiny::UA.\n", "subsections": [] }, "SEE ALSO": { "content": "o HTTP::Tiny::UA - Higher level UA features for HTTP::Tiny\n\no HTTP::Thin - HTTP::Tiny wrapper with HTTP::Request/HTTP::Response\ncompatibility\n\no HTTP::Tiny::Mech - Wrap WWW::Mechanize instance in HTTP::Tiny\ncompatible interface\n\no IO::Socket::IP - Required for IPv6 support\n\no IO::Socket::SSL - Required for SSL support\n\no LWP::UserAgent - If HTTP::Tiny isn't enough for you, this is the\n\"standard\" way to do things\n\no Mozilla::CA - Required if you want to validate SSL certificates\n\no Net::SSLeay - Required for SSL support\n", "subsections": [] }, "SUPPORT": { "content": "Bugs / Feature Requests\nPlease report any bugs or feature requests through the issue tracker at\n. You will be notified\nautomatically of any progress on your issue.\n\nSource Code\nThis is open source software. The code repository is available for\npublic review and contribution under the terms of the license.\n\n\n\ngit clone https://github.com/chansen/p5-http-tiny.git\n", "subsections": [] }, "AUTHORS": { "content": "o Christian Hansen \n\no David Golden \n", "subsections": [] }, "CONTRIBUTORS": { "content": "o Alan Gardner \n\no Alessandro Ghedini \n\no A. Sinan Unur \n\no Brad Gilbert \n\no brian m. carlson \n\no Chris Nehren \n\no Chris Weyl \n\no Claes Jakobsson \n\no Clinton Gormley \n\no Craig A. Berry \n\no Craig Berry \n\no David Golden \n\no David Mitchell \n\no Dean Pearce \n\no Edward Zborowski \n\no Felipe Gasper \n\no James Raspass \n\no Jeremy Mates \n\no Jess Robinson \n\no Karen Etheridge \n\no Lukas Eklund \n\no Martin J. Evans \n\no Martin-Louis Bright \n\no Mike Doherty \n\no Nicolas Rochelemagne \n\no Olaf Alders \n\no Olivier Mengue \n\no Petr Pisa \n\no Serguei Trouchelle \n\no Shoichi Kaji \n\no SkyMarshal \n\no Soren Kornetzki \n\no Steve Grazzini \n\no Syohei YOSHIDA \n\no Tatsuhiko Miyagawa \n\no Tom Hukins \n\no Tony Cook \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2018 by Christian Hansen.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\nperl v5.34.0 2026-06-23 HTTP::Tiny(3perl)", "subsections": [] } } } }