Redirect to ${DEFAULT_VERSION}
\n\n\" > \"${DOCS_PATH}/index.html\"\n" }, { "path": ".github/workflows/api-document.yml", "content": "name: Deploy API documents\non:\n push:\n paths-ignore:\n - \"benchmarks/**\"\n branches:\n - \"master\"\n tags:\n - \"v*\"\n\nenv:\n DOCS_PATH: docs\n GH_REF: https://github.com/icyleaf/halite\n GH_URL: https://icyleaf.github.io/halite\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@master\n with:\n # fetch all tags and branches\n fetch-depth: 0\n - uses: oprypin/install-crystal@v1\n - name: Generate\n id: generate\n run: |\n chmod +x .github/scripts/generate_docs.sh\n ./.github/scripts/generate_docs.sh\n - name: Deploy\n uses: peaceiris/actions-gh-pages@v3\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: ${{ env.DOCS_PATH }}\n\n\n" }, { "path": ".github/workflows/linux-ci.yml", "content": "name: Linux CI\non:\n push:\n paths-ignore:\n - \"benchmarks/**\"\n branches:\n - \"master\"\n pull_request:\n branches: \"*\"\n\njobs:\n specs:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n crystal: [ '1.0.0', 'latest', 'nightly' ]\n name: Crystal ${{ matrix.crystal }} tests\n steps:\n - uses: actions/checkout@master\n - uses: oprypin/install-crystal@v1\n with:\n crystal: ${{ matrix.crystal }}\n - name: Install dependencies\n run: shards install\n - name: Run tests\n run: crystal spec --error-on-warnings --error-trace\n - name: Run code format check\n run: |\n if ! crystal tool format --check; then\n crystal tool format\n git diff\n exit 1\n fi\n" }, { "path": ".github/workflows/release-version.yml", "content": "name: Deploy new release\non:\n push:\n tags:\n - \"v*\"\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@master\n - name: Create Release\n id: create_release\n uses: actions/create-release@v1\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n with:\n tag_name: ${{ github.ref }}\n release_name: Release ${{ github.ref }}\n draft: false\n prerelease: false\n\n" }, { "path": ".gitignore", "content": "docs/\nlib/\nbin/\nlogs/\n.shards/\n\n# Local test file\nmain.cr\n\n# Libraries don't need dependency lock\n# Dependencies will be locked in application that uses them\nshard.lock\n.history/\ncache/\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)\nand this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n> List all changes before release a new version.\n\n### Todo\n\n- [ ] Rewrite HTTP Connection\n - [ ] New Connection for Halite\n - [x] Proxy support\n - [ ] Reuse connection\n\n## [0.12.1] (2021-11-04)\n\n### Fixed\n\n- Reduce alloc too many memory. [#108](https://github.com/icyleaf/halite/pull/108) (thanks @[wolfgang371](https://github.com/wolfgang371))\n\n## [0.12.0] (2021-03-24)\n\n### Fixed\n\n- Compatibility with Crystal 1.0.\n\n## [0.11.0] (2021-02-18)\n\n> Finally, the major version was out! Happy new year!\n\n### Changed\n\n- **[breaking changing]** Drop file logging in favor of Crystal's [Log](https://crystal-lang.org/api/0.36.1/Log.html). (removed `.logging(file: )`, use `.logging(for: )` instead) [#101](https://github.com/icyleaf/halite/pull/101) (thanks @[oprypin](https://github.com/oprypin))\n- Pre-read `TZ` environment value to convert timestamp's timezone during logging output. [#102](https://github.com/icyleaf/halite/pull/102)\n- Crystal 0.34.x support.\n\n## [0.10.9] (2021-02-01)\n\n### Fixed\n\n- `timeout` fail to match argument type. [#97](https://github.com/icyleaf/halite/issues/97) (thanks @[oprypin](https://github.com/oprypin))\n- Compatibility with Crystal 0.36.0.\n\n## [0.10.8] (2020-12-22)\n\n### Fixed\n\n- Resolve path of endpoint ending without slash. [#94](https://github.com/icyleaf/halite/issues/94) (thanks @[mipmip](https://github.com/mipmip))\n\n## [0.10.7] (2020-12-08)\n### Fixed\n\n- Fix initial status_message. [#91](https://github.com/icyleaf/halite/issues/91) (thanks @[oprypin](https://github.com/oprypin))\n\n## [0.10.6] (2020-11-24)\n### Fixed\n\n- Improve resolve of URI. [#88](https://github.com/icyleaf/halite/issues/88) (thanks @[oprypin](https://github.com/oprypin))\n\n## [0.10.5] (2020-04-15)\n\n### Fixed\n\n- Compatibility with Crystal 0.34.0.\n\n## [0.10.4] (2019-09-26)\n\n### Fixed\n\n- Compatibility with Crystal 0.31.0.\n\n## [0.10.3] (2019-08-12)\n\n### Fixed\n\n- Compatibility with Crystal 0.30.0.\n\n## [0.10.2] (2019-06-24)\n\n### Fixed\n\n- Fixed Basic Auth creates bad headers in crystal 0.29.0. [#73](https://github.com/icyleaf/halite/pull/73) (thanks @[kalinon](https://github.com/kalinon))\n- Fixed use one shared options in multiple instanced `Halite::Client`. [#72](https://github.com/icyleaf/halite/issues/72) (thanks @[qszhu](https://github.com/qszhu))\n\n## [0.10.1] (2019-05-28)\n\n### Fixed\n\n- Fixed duplica query and backslash when reuse client. [#67](https://github.com/icyleaf/halite/pull/67), [#68](https://github.com/icyleaf/halite/issues/68) (thanks @[watzon](https://github.com/watzon))\n- Fixed no effect to call `logging(true)` method in Crystal 0.28. [#69](https://github.com/icyleaf/halite/issues/69)\n\n## [0.10.0] (2019-05-20)\n\n### Added\n\n- Add `endpoint` chainable method, also add it as configuration option to reuse client. [#66](https://github.com/icyleaf/halite/pull/66)\n\n## [0.9.2] (2019-05-20)\n\n### Fixed\n\n- Compatibility with Crystal 0.28.0\n\n### Changed\n\n- Drop Crystal 0.25.x, 0.26.x, 0.27.x support.\n\n## [0.9.1] (2019-01-14)\n\n> Minor typo fix (same as v0.9.0)\n\n### Fixed\n\n- Correct version both in `shard.yml` and `version.cr`. (thanks @[matthewmcgarvey](https://github.com/matthewmcgarvey))\n- Update basic auth example in `README.md`. (thanks @[matthewmcgarvey](https://github.com/matthewmcgarvey))\n\n## [0.9.0] (2018-12-21)\n\n> New features with performance improved.\n\n### Added\n\n- Add streaming requests (feature to store binary data chunk by chunk) [#53](https://github.com/icyleaf/halite/pull/53)\n- Add `user_agent` to Chainable methods. [#55](https://github.com/icyleaf/halite/pull/55)\n\n### Fixed\n\n- Fix overwrite the value with default headers when use `merge` or `merge!` method in `Halite::Options`. [#54](https://github.com/icyleaf/halite/pull/54)\n\n### Changed\n\n- Remove default headers in `Halite::Options`.\n- Move header `User-Agent` to `Halite::Request`.\n- Change header `Connection` from \"keep-alive\" to \"close\" to `Halite::Request`.\n- Remove header `Accept`.\n\n## [0.8.0] (2018-11-30)\n\n> Compatibility with Crystal 0.27 and serious bugfix.\n\n### Changed\n\n- **[breaking changing]** Rename `logger` to `logging`, `with_logger` to `with_logging`. [#52](https://github.com/icyleaf/halite/pull/52)\n- **[breaking changing]** Remove `logging` argument in `Halite::Options.new` and `Halite::Client.new`. [#51](https://github.com/icyleaf/halite/pull/51)\n- **[breaking changing]** Remove `logging?` method in `Halite::Options`, use `logging` method instead. [#51](https://github.com/icyleaf/halite/pull/51)\n- Change `logging` behavior check if features is exists any class of superclasses is `Halite::Logging` instead of given a Bool type.\n- Rename prefix `X-Cache` to `X-Halite-Cache` in cache feature.\n\n### Added\n\n- Allow `timeout` method passed single `read` or `connect` method.\n- Add `merge!` and `dup` methods in `Halite::Options`. [#51](https://github.com/icyleaf/halite/pull/51)\n\n### Fixed\n\n- Fix duplice add \"Content-Type\" into header during request. [#50](https://github.com/icyleaf/halite/pull/50)\n- Fix non overwrite value of headers use `Halite::Options.merge` method. [#50](https://github.com/icyleaf/halite/pull/50)\n- Fix always overwrite and return merged option in a instanced class(session mode), see updated note in [Session](https://github.com/icyleaf/halite#sessions).\n\n### Tested\n\n- Compatibility with Crystal 0.27\n- Add specs with Crystal 0.25, 0.26 and 0.27 in Circle CI.\n\n## [0.7.5] (2018-10-31)\n\n### Changed\n\n- **[breaking changing]** Rename argument name `ssl` to `tls` in `Halite::Client`/`Halite::Options`/`Halite::Chainable`.\n\n### Fixed\n\n- Fix new a `Halite::Client` instance with empty block return `Nil`. [#44](https://github.com/icyleaf/halite/issues/44)\n\n## [0.7.4] (2018-10-30)\n\n### Fixed\n\n- Fix typos in document and comments. [#43](https://github.com/icyleaf/halite/issues/43) (thanks @[GloverDonovan](https://github.com/GloverDonovan))\n\n## [0.7.3] (2018-10-18)\n\n### Fixed\n\n- Fix json payloads with sub hash/array/namedtupled. [#41](https://github.com/icyleaf/halite/issues/41) (thanks @[fusillicode](https://github.com/fusillicode))\n\n## [0.7.2] (2018-09-14)\n\n> Minor bugfix :bug:\n\n### Changed\n\n- **[breaking changing]** Renamed `#to_h` to `#to_flat_h` to avoid confict in `HTTP::Params` extension. [#39](https://github.com/icyleaf/halite/issues/39)\n\n### Fixed\n\n- Fix cast from NamedTuple(work: String) to Halite::Options::Type failed with params/json/form. [#38](https://github.com/icyleaf/halite/issues/38)\n\n## [0.7.1] (2018-09-04)\n\n### Changed\n\n- Return empty hash for an empty named tuple.\n\n### Fixed\n\n- Fix send cookie during requesting in session mode. (thanks @[megatux](https://github.com/megatux))\n- Fix pass current options instead of instance variable.\n- Fix move named tuple extension to src path.\n\n## [0.7.0] (2018-09-03)\n\n> Features support :tada:\n\n### Changed\n\n- **[breaking changing]** Change instance `Halite::Client` with block behavior. [#33](https://github.com/icyleaf/halite/issues/33)\n- **[breaking changing]** Renamed argument name `adapter` to `format` in `#logger` chainable method.\n- Move logger into features.\n\n### Added\n\n- Add features (aka middleware) support, you can create monitor or interceptor. [#29](https://github.com/icyleaf/halite/issues/29)\n- Add cache feature. [#24](https://github.com/icyleaf/halite/issues/24)\n- Add `#logging` in chainable method.\n\n### Fixed\n\n- Add misisng `#request` method with headers, params, form, json, raw, ssl arguments.\n- Fix do not overwrite default headers with exists one by using `Halite::Options.merge`.\n- Fix append response to history only with redirect uri. (thanks @[j8r](https://github.com/j8r))\n- Typo and correct words in README. (thanks @[megatux](https://github.com/megatux))\n\n## [0.6.0] (2018-08-24)\n\n> Improve performance with :see_no_evil:\n\n### Changed\n\n- **[breaking changing]** Set `logger` to nil when instance a `Halite::Options`, it throws a `Halite::Error` exception if enable `logging`.\n- Change `Halite::Options` accepts argument inside. no effect for users. [#27](https://github.com/icyleaf/halite/pull/27)\n- Wrap all exception class into a module, better for reading document.\n\n### Fixed\n\n- Fix always return `#` with `#full_path` if fragment not exists in `Halite::Request`.\n- Fix always overwrite with default headers with `#merge` in `Halite::Options`\n\n### Tested\n\n- Compatibility with Crystal 0.26\n\n## [0.5.0] (2018-07-03)\n\n### Changed\n\n- New logger system and json logger support, see [#19](https://github.com/icyleaf/halite/pull/19).\n- **[breaking changing]** Change verb request behavior:\n - `get`, `head` only accepts `#params` argument.\n - `post`, `put`, `delete`, `patch`, `options` accepts `#params`, `#form`, `#json` and `#raw` arguments.\n\n### Added\n\n- Add request [#raw](https://github.com/icyleaf/halite/#raw-string) string support. [#20](https://github.com/icyleaf/halite/issues/20) (thanks @[wirrareka](https://github.com/wirrareka))\n\n## [0.4.0] (2018-06-27)\n\n### Changed\n\n- **[breaking changing]** Remove `#mime_type` duplicate with `#content_type` in `Halite::Response`.\n- Change write log file use append mode by default, it could be change by param.\n- Change logger formatter to easy identify category(request/response).\n\n### Added\n\n- Add [#links](https://github.com/icyleaf/halite/#link-headers) to `Halite::Response` to fetch link headers.\n- Add [#raise_for_status](https://github.com/icyleaf/halite/#raise-for-status-code) to `Halite::Response`.\n- Support multiple files upload. [#14](https://github.com/icyleaf/halite/issues/14) (thanks @[BenDietze](https://github.com/BenDietze))\n- Add `#to_raw` to `Halite::Response` to dump a raw of response. [#15](https://github.com/icyleaf/halite/issues/15) (thanks @[BenDietze](https://github.com/BenDietze))\n- Support `OPTIONS` method (crystal 0.25.0+)\n- Append write log to a file section to README.\n\n### Fixed\n\n- Stripped the filename in a `multipart/form-data` body. [#16](https://github.com/icyleaf/halite/issues/16) (thanks @[BenDietze](https://github.com/BenDietze))\n- Fix `#domain` in `Halite::Request` with subdomain. [#17](https://github.com/icyleaf/halite/pull/17) (thanks @[007lva](https://github.com/007lva))\n- Create missing directories when use path to write log to a file.\n\n## [0.3.2] (2018-06-19)\n\n### Fixed\n\nCompatibility with Crystal 0.25\n\n## [0.3.1] (2017-12-13)\n\n### Added\n\n- Set `Options.default_headers` to be public method.\n- Accept tuples options in `Options.new`.\n- Accept `follow`/`follow_strict` in `Options.new`.\n- Accept options block in `Options.new`.\n- Add logger during request and response (see [usage](README.md#logging)).\n- Alias method `Options.read_timeout` to `Options::Timeout.read`.\n- Alias method `Options.read_timeout=` to `Options::Timeout.read=`.\n- Alias method `Options.connect_timeout` to `Options::Timeout.connect`.\n- Alias method `Options.connect_timeout` to `Options::Timeout.connect=`.\n- Alias method `Options.follow=` to `Options::Timeout.follow.hops=`.\n- Alias method `Options.follow_strict` to `Options::Timeout.follow.strict`.\n- Alias method `Options.follow_strict=` to `Options::Timeout.follow.strict=`.\n\n### Fixed\n\n- Fix store **Set-Cookies** in response and set **Cookies** in request in better way.\n- Fix cant not set connect/read timeout in `Options.new`.\n- Fix cant not overwrite default headers in `Options.new`.\n- Fix `Options.clear!` was not clear everything and restore default headers.\n\n## [0.2.0] (2017-11-28)\n\n### Changed\n\n- `HTTP::Headers#to_h` return string with each key if it contains one in array. ([commit#e057c47c](https://github.com/icyleaf/halite/commit/e057c47c4b587b27b2bae6871a1968299ce348f5))\n\n### Added\n\n- Add `Response#mime_type` method.\n- Add `Response#history` method to support full history of redirections. ([#8](https://github.com/icyleaf/halite/issues/8))\n- Add `Response#parse` method that it better body parser of response with json and write custom adapter for MIME type. ([#9](https://github.com/icyleaf/halite/issues/9))\n\n### Fixed\n\n- Fix issue to first char of redirect uri is not slash(/). ([#11](https://github.com/icyleaf/halite/issues/11))\n- Fix raise unsafe verbs in strict mode.\n\n## [0.1.5] (2017-10-11)\n\n### Changed\n\n- Only store cookies in Sessions shards. ([#7](https://github.com/icyleaf/halite/issues/7))\n\n### Added\n\n- Add `TLS/SSL` support (based on [HTTP::Client.new(uri : URI, tls = nil)](https://crystal-lang.org/api/0.23.1/HTTP/Client.html#new%28uri%3AURI%2Ctls%3Dnil%29-class-method)).\n- Add `UnsupportedMethodError/UnsupportedSchemeError` exceptions.\n\n### Fixed\n\n- Timeout with redirection. ([#7](https://github.com/icyleaf/halite/issues/7))\n- Compatibility with Crystal 0.24.0 (unreleased)\n\n## [0.1.3] (2017-10-09)\n\n### Changed\n\n- Always instance a new Options with each request in chainable methods.\n\n### Added\n\n- Add `accept` method.\n\n### Fixed\n\n- Fix `follow`(redirect uri) with full uri and relative path.\n- Fix always overwrite request headers with default values.\n- Fix always shard same options in any new call. (it only valid in chainable methods)\n\n## 0.1.2 (2017-09-18)\n\n- First beta version.\n\n[Unreleased]: https://github.com/icyleaf/halite/compare/v0.12.1...HEAD\n[0.12.1]: https://github.com/icyleaf/halite/compare/v0.12.0...v0.12.1\n[0.12.0]: https://github.com/icyleaf/halite/compare/v0.11.0...v0.12.0\n[0.11.0]: https://github.com/icyleaf/halite/compare/v0.10.9...v0.11.0\n[0.10.9]: https://github.com/icyleaf/halite/compare/v0.10.8...v0.10.9\n[0.10.8]: https://github.com/icyleaf/halite/compare/v0.10.7...v0.10.8\n[0.10.7]: https://github.com/icyleaf/halite/compare/v0.10.6...v0.10.7\n[0.10.6]: https://github.com/icyleaf/halite/compare/v0.10.5...v0.10.6\n[0.10.5]: https://github.com/icyleaf/halite/compare/v0.10.4...v0.10.5\n[0.10.4]: https://github.com/icyleaf/halite/compare/v0.10.3...v0.10.4\n[0.10.3]: https://github.com/icyleaf/halite/compare/v0.10.2...v0.10.3\n[0.10.2]: https://github.com/icyleaf/halite/compare/v0.10.1...v0.10.2\n[0.10.1]: https://github.com/icyleaf/halite/compare/v0.10.0...v0.10.1\n[0.10.0]: https://github.com/icyleaf/halite/compare/v0.9.2...v0.10.0\n[0.9.2]: https://github.com/icyleaf/halite/compare/v0.9.1...v0.9.2\n[0.9.1]: https://github.com/icyleaf/halite/compare/v0.9.0...v0.9.1\n[0.9.0]: https://github.com/icyleaf/halite/compare/v0.8.0...v0.9.0\n[0.8.0]: https://github.com/icyleaf/halite/compare/v0.7.5...v0.8.0\n[0.7.5]: https://github.com/icyleaf/halite/compare/v0.7.4...v0.7.5\n[0.7.4]: https://github.com/icyleaf/halite/compare/v0.7.3...v0.7.4\n[0.7.3]: https://github.com/icyleaf/halite/compare/v0.7.2...v0.7.3\n[0.7.2]: https://github.com/icyleaf/halite/compare/v0.7.1...v0.7.2\n[0.7.1]: https://github.com/icyleaf/halite/compare/v0.7.0...v0.7.1\n[0.7.0]: https://github.com/icyleaf/halite/compare/v0.6.0...v0.7.0\n[0.6.0]: https://github.com/icyleaf/halite/compare/v0.5.0...v0.6.0\n[0.5.0]: https://github.com/icyleaf/halite/compare/v0.4.0...v0.5.0\n[0.4.0]: https://github.com/icyleaf/halite/compare/v0.3.2...v0.4.0\n[0.3.2]: https://github.com/icyleaf/halite/compare/v0.3.1...v0.3.2\n[0.3.1]: https://github.com/icyleaf/halite/compare/v0.2.0...v0.3.1\n[0.2.0]: https://github.com/icyleaf/halite/compare/v0.1.5...v0.2.0\n[0.1.5]: https://github.com/icyleaf/halite/compare/v0.1.3...v0.1.5\n[0.1.3]: https://github.com/icyleaf/halite/compare/v0.1.2...v0.1.3\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment include:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at icyleaf.cn@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]\n\n[homepage]: http://contributor-covenant.org\n[version]: http://contributor-covenant.org/version/1/4/\n" }, { "path": "LICENSE", "content": "The MIT License (MIT)\n\nCopyright (c) 2017-present icyleaf\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n" }, { "path": "README.md", "content": "\n\n# Halite\n\n[](https://github.com/crystal-lang/crystal)\n[](https://github.com/icyleaf/halite/blob/master/CHANGELOG.md)\n[](https://github.com/icyleaf/halite/)\n[](https://icyleaf.github.io/halite/)\n[](https://github.com/icyleaf/halite/actions?query=workflow%3A%22Linux+CI%22)\n\nHTTP Requests with a chainable REST API, built-in sessions and middleware written by [Crystal](https://crystal-lang.org/).\nInspired from the **awesome** Ruby's [HTTP](https://github.com/httprb/http)/[RESTClient](https://github.com/rest-client/rest-client)\nand Python's [requests](https://github.com/requests/requests).\n\nBuild in Crystal version `>= 1.0.0`, this document valid with latest commit.\n\n## Index\n\n\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Making Requests](#making-requests)\n - [Passing Parameters](#passing-parameters)\n - [Query string parameters](#query-string-parameters)\n - [Form data](#form-data)\n - [File uploads (via form data)](#file-uploads-via-form-data)\n - [JSON data](#json-data)\n - [Raw String](#raw-string)\n - [Passing advanced options](#passing-advanced-options)\n - [Auth](#auth)\n - [User Agent](#user-agent)\n - [Headers](#headers)\n - [Cookies](#cookies)\n - [Redirects and History](#redirects-and-history)\n - [Timeout](#timeout)\n - [HTTPS](#https)\n - [Response Handling](#response-handling)\n - [Response Content](#response-content)\n - [JSON Content](#json-content)\n - [Parsing Content](#parsing-content)\n - [Binary Data](#binary-data)\n - [Error Handling](#error-handling)\n - [Raise for status code](#raise-for-status-code)\n- [Middleware](#middleware)\n - [Write a simple feature](#write-a-simple-feature)\n - [Write a interceptor](#write-a-interceptor)\n- [Advanced Usage](#advanced-usage)\n - [Configuring](#configuring)\n - [Endpoint](#endpoint)\n - [Sessions](#sessions)\n - [Streaming Requests](#streaming-requests)\n - [Logging](#logging)\n - [Local Cache](#local-cache)\n - [Link Headers](#link-headers)\n\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n halite:\n github: icyleaf/halite\n```\n\n## Usage\n\n```crystal\nrequire \"halite\"\n```\n\n### Making Requests\n\nMake a GET request:\n\n```crystal\n# Direct get url\nHalite.get(\"http://httpbin.org/get\")\n\n# Support NamedTuple as query params\nHalite.get(\"http://httpbin.org/get\", params: {\n language: \"crystal\",\n shard: \"halite\"\n})\n\n# Also support Hash as query params\nHalite.get(\"http://httpbin.org/get\", headers: {\n \"Private-Token\" => \"T0k3n\"\n }, params: {\n \"language\" => \"crystal\",\n \"shard\" => \"halite\"\n })\n\n# And support chainable\nHalite.header(private_token: \"T0k3n\")\n .get(\"http://httpbin.org/get\", params: {\n \"language\" => \"crystal\",\n \"shard\" => \"halite\"\n })\n```\n\nSee also all [chainable methods](https://icyleaf.github.io/halite/Halite/Chainable.html).\n\nMany other HTTP methods are available as well:\n\n- `get`\n- `head`\n- `post`\n- `put`\n- `delete`\n- `patch`\n- `options`\n\n### Passing Parameters\n\n#### Query string parameters\n\nUse the `params` argument to add query string parameters to requests:\n\n```crystal\nHalite.get(\"http://httpbin.org/get\", params: { \"firstname\" => \"Olen\", \"lastname\" => \"Rosenbaum\" })\n```\n\n#### Form data\n\nUse the `form` argument to pass data serialized as form encoded:\n\n```crystal\nHalite.post(\"http://httpbin.org/post\", form: { \"firstname\" => \"Olen\", \"lastname\" => \"Rosenbaum\" })\n```\n\n#### File uploads (via form data)\n\nTo upload files as if form data, construct the form as follows:\n\n```crystal\nHalite.post(\"http://httpbin.org/post\", form: {\n \"username\" => \"Quincy\",\n \"avatar\" => File.open(\"/Users/icyleaf/quincy_avatar.png\")\n})\n```\n\nIt is possible to upload multiple files:\n\n```crystal\nHalite.post(\"http://httpbin.org/post\", form: {\n photos: [\n File.open(\"/Users/icyleaf/photo1.png\"),\n File.open(\"/Users/icyleaf/photo2.png\")\n ],\n album_name: \"samples\"\n})\n```\n\nOr pass the name with `[]`:\n\n```crystal\nHalite.post(\"http://httpbin.org/post\", form: {\n \"photos[]\" => [\n File.open(\"/Users/icyleaf/photo1.png\"),\n File.open(\"/Users/icyleaf/photo2.png\")\n ],\n \"album_name\" => \"samples\"\n})\n```\n\nMultiple files can also be uploaded using both ways above, it depend on web server.\n\n#### JSON data\n\nUse the `json` argument to pass data serialized as body encoded:\n\n```crystal\nHalite.post(\"http://httpbin.org/post\", json: { \"firstname\" => \"Olen\", \"lastname\" => \"Rosenbaum\" })\n```\n\n#### Raw String\n\nUse the `raw` argument to pass raw string as body and set the `Content-Type` manually:\n\n```crystal\n# Set content-type to \"text/plain\" by default\nHalite.post(\"http://httpbin.org/post\", raw: \"name=Peter+Lee&address=%23123+Happy+Ave&language=C%2B%2B\")\n\n# Set content-type manually\nHalite.post(\"http://httpbin.org/post\",\n headers: {\n \"content-type\" => \"application/json\"\n },\n raw: %Q{{\"name\":\"Peter Lee\",\"address\":\"23123 Happy Ave\",\"language\":\"C++\"}}\n)\n```\n\n### Passing advanced options\n\n#### Auth\n\nUse the `#basic_auth` method to perform [HTTP Basic Authentication](http://tools.ietf.org/html/rfc2617) using a username and password:\n\n```crystal\nHalite.basic_auth(user: \"user\", pass: \"p@ss\").get(\"http://httpbin.org/get\")\n\n# We can pass a raw authorization header using the auth method:\nHalite.auth(\"Bearer dXNlcjpwQHNz\").get(\"http://httpbin.org/get\")\n```\n\n#### User Agent\n\nUse the `#user_agent` method to overwrite default one:\n\n```crystal\nHalite.user_agent(\"Crystal Client\").get(\"http://httpbin.org/user-agent\")\n```\n\n#### Headers\n\nHere are two way to passing headers data:\n\n##### 1. Use the `#headers` method\n\n```crystal\nHalite.headers(private_token: \"T0k3n\").get(\"http://httpbin.org/get\")\n\n# Also support Hash or NamedTuple\nHalite.headers({ \"private_token\" => \"T0k3n\" }).get(\"http://httpbin.org/get\")\n\n# Or\nHalite.headers({ private_token: \"T0k3n\" }).get(\"http://httpbin.org/get\")\n```\n\n##### 2. Use the `headers` argument in the available request method:\n\n```crystal\nHalite.get(\"http://httpbin.org/anything\" , headers: { private_token: \"T0k3n\" })\n\nHalite.post(\"http://httpbin.org/anything\" , headers: { private_token: \"T0k3n\" })\n```\n\n#### Cookies\n\n##### Passing cookies in requests\n\nThe `Halite.cookies` option can be used to configure cookies for a given request:\n\n```crystal\nHalite.cookies(session_cookie: \"6abaef100b77808ceb7fe26a3bcff1d0\")\n .get(\"http://httpbin.org/headers\")\n```\n\n##### Get cookies in requests\n\nTo obtain the cookies(cookie jar) for a given response, call the `#cookies` method:\n\n```crystal\nr = Halite.get(\"http://httpbin.org/cookies?set?session_cookie=6abaef100b77808ceb7fe26a3bcff1d0\")\npp r.cookies\n# => #You should be redirected automatically to target URL: /cookies. If not click the link.\n# => 2018-06-25 18:41:06 +08:00 | request | GET | http://httpbin.org/cookies\n# => 2018-06-25 18:41:07 +08:00 | response | 200 | http://httpbin.org/cookies | application/json\n# => {\"cookies\":{\"private_token\":\"6abaef100b77808ceb7fe26a3bcff1d0\"}}\n```\n\nAll it support with [chainable methods](https://icyleaf.github.io/halite/Halite/Chainable.html) in the other examples list in [requests.Session](http://docs.python-requests.org/en/master/user/advanced/#session-objects).\n\nNote, however, that chainable methods will not be persisted across requests, even if using a session. This example will only send the cookies or headers with the first request, but not the second:\n\n```crystal\nclient = Halite::Client.new\nr = client.cookies(\"username\": \"foobar\").get(\"http://httpbin.org/cookies\")\nr.body # => {\"cookies\":{\"username\":\"foobar\"}}\n\nr = client.get(\"http://httpbin.org/cookies\")\nr.body # => {\"cookies\":{}}\n```\n\nIf you want to manually add cookies, headers (even features etc) to your session, use the methods start with `with_` in `Halite::Options`\nto manipulate them:\n\n```crystal\nr = client.get(\"http://httpbin.org/cookies\")\nr.body # => {\"cookies\":{}}\n\nclient.options.with_cookie(\"username\": \"foobar\")\nr = client.get(\"http://httpbin.org/cookies\")\nr.body # => {\"cookies\":{\"username\":\"foobar\"}}\n```\n\n### Streaming Requests\n\nSimilar to [HTTP::Client](https://crystal-lang.org/api/0.36.1/HTTP/Client.html#streaming) usage with a block,\nyou can easily use same way, but Halite returns a `Halite::Response` object:\n\n```crystal\nr = Halite.get(\"http://httpbin.org/stream/5\") do |response|\n response.status_code # => 200\n response.body_io.each_line do |line|\n puts JSON.parse(line) # => {\"url\" => \"http://httpbin.org/stream/5\", \"args\" => {}, \"headers\" => {\"Host\" => \"httpbin.org\", \"Connection\" => \"close\", \"User-Agent\" => \"Halite/0.8.0\", \"Accept\" => \"*/*\", \"Accept-Encoding\" => \"gzip, deflate\"}, \"id\" => 0_i64}\n end\nend\n```\n\n> **Warning**:\n>\n> `body_io` is avaiabled as an `IO` and not reentrant safe. Might throws a \"Nil assertion failed\" exception if there is no data in the `IO`\n(such like `head` requests). Calling this method multiple times causes some of the received data being lost.\n>\n> One more thing, use streaming requests the response will always [enable redirect](#redirects-and-history) automatically.\n\n### Logging\n\nHalite does not enable logging on each request and response too.\nWe can enable per operation logging by configuring them through the chaining API.\n\nBy default, Halite will logging all outgoing HTTP requests and their responses(without binary stream) to `STDOUT` on DEBUG level.\nYou can configuring the following options:\n\n- `logging`: Instance your `Halite::Logging::Abstract`, check [Use the custom logging](#use-the-custom-logging).\n- `format`: Output format, built-in `common` and `json`, you can write your own.\n- `file`: Write to file with path, works with `format`.\n- `filemode`: Write file mode, works with `format`, by default is `a`. (append to bottom, create it if file is not exist)\n- `skip_request_body`: By default is `false`.\n- `skip_response_body`: By default is `false`.\n- `skip_benchmark`: Display elapsed time, by default is `false`.\n- `colorize`: Enable colorize in terminal, only apply in `common` format, by default is `true`.\n\n> **NOTE**: `format` (`file` and `filemode`) and `logging` are conflict, you can not use both.\n\nLet's try with it:\n\n```crystal\n# Logging json request\nHalite.logging\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n\n# => 2018-06-25 18:33:14 +08:00 | request | GET | http://httpbin.org/get?name=foobar\n# => 2018-06-25 18:33:15 +08:00 | response | 200 | http://httpbin.org/get?name=foobar | 381.32ms | application/json\n# => {\"args\":{\"name\":\"foobar\"},\"headers\":{\"Accept\":\"*/*\",\"Accept-Encoding\":\"gzip, deflate\",\"Connection\":\"close\",\"Host\":\"httpbin.org\",\"User-Agent\":\"Halite/0.3.2\"},\"origin\":\"60.206.194.34\",\"url\":\"http://httpbin.org/get?name=foobar\"}\n\n# Logging image request\nHalite.logging\n .get(\"http://httpbin.org/image/png\")\n\n# => 2018-06-25 18:34:15 +08:00 | request | GET | http://httpbin.org/image/png\n# => 2018-06-25 18:34:15 +08:00 | response | 200 | http://httpbin.org/image/png | image/png\n\n# Logging with options\nHalite.logging(skip_request_body: true, skip_response_body: true)\n .post(\"http://httpbin.org/get\", form: {image: File.open(\"halite-logo.png\")})\n\n# => 2018-08-28 14:33:19 +08:00 | request | POST | http://httpbin.org/post\n# => 2018-08-28 14:33:21 +08:00 | response | 200 | http://httpbin.org/post | 1.61s | application/json\n```\n\n#### JSON-formatted logging\n\nIt has JSON formatted for developer friendly logging.\n\n```\nHalite.logging(format: \"json\")\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n```\n\n#### Write to a log file\n\n```crystal\n# Write plain text to a log file\nLog.setup(\"halite.file\", backend: Log::IOBackend.new(File.open(\"/tmp/halite.log\", \"a\")))\nHalite.logging(for: \"halite.file\", skip_benchmark: true, colorize: false)\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n\n# Write json data to a log file\nLog.setup(\"halite.file\", backend: Log::IOBackend.new(File.open(\"/tmp/halite.log\", \"a\")))\nHalite.logging(format: \"json\", for: \"halite.file\")\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n\n# Redirect *all* logging from Halite to a file:\nLog.setup(\"halite\", backend: Log::IOBackend.new(File.open(\"/tmp/halite.log\", \"a\")))\n```\n\n#### Use the custom logging\n\nCreating the custom logging by integration `Halite::Logging::Abstract` abstract class.\nHere has two methods must be implement: `#request` and `#response`.\n\n```crystal\nclass CustomLogging < Halite::Logging::Abstract\n def request(request)\n @logger.info { \"| >> | %s | %s %s\" % [request.verb, request.uri, request.body] }\n end\n\n def response(response)\n @logger.info { \"| << | %s | %s %s\" % [response.status_code, response.uri, response.content_type] }\n end\nend\n\n# Add to adapter list (optional)\nHalite::Logging.register \"custom\", CustomLogging.new\n\nHalite.logging(logging: CustomLogging.new)\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n\n# We can also call it use format name if you added it.\nHalite.logging(format: \"custom\")\n .get(\"http://httpbin.org/get\", params: {name: \"foobar\"})\n\n# => 2017-12-13 16:40:13 +08:00 | >> | GET | http://httpbin.org/get?name=foobar\n# => 2017-12-13 16:40:15 +08:00 | << | 200 | http://httpbin.org/get?name=foobar application/json\n```\n\n### Local Cache\n\nLocal cache feature is caching responses easily with Halite through an chainable method that is simple and elegant\nyet powerful. Its aim is to focus on the HTTP part of caching and do not worrying about how stuff stored, api rate limiting\neven works without network(offline).\n\nIt has the following options:\n\n- `file`: Load cache from file. it conflict with `path` and `expires`.\n- `path`: The path of cache, default is \"/tmp/halite/cache/\"\n- `expires`: The expires time of cache, default is never expires.\n- `debug`: The debug mode of cache, default is `true`\n\nWith debug mode, cached response it always included some headers information:\n\n- `X-Halite-Cached-From`: Cache source (cache or file)\n- `X-Halite-Cached-Key`: Cache key with verb, uri and body (return with cache, not `file` passed)\n- `X-Halite-Cached-At`: Cache created time\n- `X-Halite-Cached-Expires-At`: Cache expired time (return with cache, not `file` passed)\n\n```crystal\nHalite.use(\"cache\").get \"http://httpbin.org/anything\" # request a HTTP\nr = Halite.use(\"cache\").get \"http://httpbin.org/anything\" # request from local storage\nr.headers # => {..., \"X-Halite-Cached-At\" => \"2018-08-30 10:41:14 UTC\", \"X-Halite-Cached-By\" => \"Halite\", \"X-Halite-Cached-Expires-At\" => \"2018-08-30 10:41:19 UTC\", \"X-Halite-Cached-Key\" => \"2bb155e6c8c47627da3d91834eb4249a\"}}\n```\n\n### Link Headers\n\nMany HTTP APIs feature [Link headers](https://tools.ietf.org/html/rfc5988). GitHub uses\nthese for [pagination](https://developer.github.com/v3/#pagination) in their API, for example:\n\n```crystal\nr = Halite.get \"https://api.github.com/users/icyleaf/repos?page=1&per_page=2\"\nr.links\n# => {\"next\" =>\n# => Halite::HeaderLink(\n# => @params={},\n# => @rel=\"next\",\n# => @target=\"https://api.github.com/user/17814/repos?page=2&per_page=2\"),\n# => \"last\" =>\n# => Halite::HeaderLink(\n# => @params={},\n# => @rel=\"last\",\n# => @target=\"https://api.github.com/user/17814/repos?page=41&per_page=2\")}\n\nr.links[\"next\"]\n# => \"https://api.github.com/user/17814/repos?page=2&per_page=2\"\n\nr.links[\"next\"].params\n# => {}\n```\n\n## Help and Discussion\n\nYou can browse the API documents:\n\nhttps://icyleaf.github.io/halite/\n\nYou can browse the all chainable methods:\n\nhttps://icyleaf.github.io/halite/Halite/Chainable.html\n\nYou can browse the Changelog:\n\nhttps://github.com/icyleaf/halite/blob/master/CHANGELOG.md\n\nIf you have found a bug, please create a issue here:\n\nhttps://github.com/icyleaf/halite/issues/new\n\n## How to Contribute\n\nYour contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.\n\nAll [Contributors](https://github.com/icyleaf/halite/graphs/contributors) are on the wall.\n\n## You may also like\n\n- [totem](https://github.com/icyleaf/totem) - Load and parse a configuration file or string in JSON, YAML, dotenv formats.\n- [markd](https://github.com/icyleaf/markd) - Yet another markdown parser built for speed, Compliant to CommonMark specification.\n- [poncho](https://github.com/icyleaf/poncho) - A .env parser/loader improved for performance.\n- [popcorn](https://github.com/icyleaf/popcorn) - Easy and Safe casting from one type to another.\n- [fast-crystal](https://github.com/icyleaf/fast-crystal) - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.\n\n## License\n\n[MIT License](https://github.com/icyleaf/halite/blob/master/LICENSE) © icyleaf\n"
},
{
"path": "shard.yml",
"content": "name: halite\nversion: 0.12.1\n\nauthors:\n - icyleaf