[ { "path": ".editorconfig", "content": "root = true\n\n[*.rs]\ninsert_final_newline = true\ntrim_trailing_whitespace = true\nindent_style = space\nindent_size = 4\ntab_width = 4\n" }, { "path": ".gitattributes", "content": "* text eol=lf\n\n# Denote all files that are truly binary and should not be modified.\n*.png binary\n*.jpg binary\n*.gif binary\n*.svg binary\n" }, { "path": ".github/CODE_OF_CONDUCT.md", "content": "# Rocket Community Code of Conduct\n\nLike the technical community as a whole, the Rocket project, its teams, and its\ncommunity are made up of a mixture of professionals and volunteers from all over\nthe world, working on every aspect of the mission. Diversity is one of our huge\nstrengths, but it can also lead to communication issues and unhappiness. To that\nend, we have a few ground rules that we ask people to adhere to. This code\napplies equally to everyone in our community: maintainers, contributors, team\nleads, mentors, those seeking help and guidance, and so on.\n\nThis isn’t an exhaustive list of things that you can’t do. Rather, take it in\nthe spirit in which it’s intended - a guide to make it easier to enrich all of\nus and the technical communities in which we participate.\n\n_If you believe someone is violating the code of conduct, we ask that you report\nit by emailing community@rwf2.org._\n\n- **Be friendly. Be Kind. Be patient.**\n\n- **Be welcoming.** We strive to be a community that welcomes and supports\n everyone, of all backgrounds and identities. This includes, but is not limited\n to members of any race, ethnicity, culture, national origin, color,\n immigration status, social and economic class, educational level, sex, sexual\n orientation, gender identity and expression, age, size, family status,\n political belief, religion, and mental and physical ability.\n\n- **Be considerate.** Your work will be used by other people, and you in turn\n will depend on the work of others. Any decision you take will affect users and\n colleagues, and you should take those consequences into account when making\n decisions. Remember that we're a global community, so you might not be\n communicating in someone else's primary language.\n\n- **Be respectful.** We won't all agree all the time, but disagreement isn't an\n excuse for poor behavior or poor manners. While frustrations may occasionally\n arise, we cannot allow those frustrations to turn into personal attacks.\n Remember that a community where people feel uncomfortable or threatened is not\n a productive one. Be respectful, not just to fellow community members, but to\n individuals outside the community as well.\n\n- **Be careful in the words that you choose.** We are a community of\n professionals, and we conduct ourselves professionally. Do not insult or put\n down other participants. Harassment and other exclusionary behavior aren't\n acceptable. This includes, but is not limited to:\n - Violent threats or language directed against another person.\n - Discriminatory jokes and language.\n - Posting sexually explicit or violent material.\n - Posting (or threatening to post) other people's personally identifying\n information (\"doxing\").\n - Personal insults, especially those using racist or sexist terms.\n - Unwelcome sexual attention.\n - Advocating for, or encouraging, any of the above behavior.\n - Repeated harassment of others. In general, if someone asks you to stop, then\n stop.\n\n- **Be understanding.** Disagreements, both social and technical, happen all the\n time. It is important that we resolve differing views constructively. When we\n disagree, try to understand why. Our community consists of people from a wide\n range of backgrounds. Different people have different perspectives on issues.\n Being unable to understand why someone holds a viewpoint doesn’t mean that\n they’re wrong. Don’t forget that it is human to err; blame accomplishes\n nothing. Instead, focus on helping to resolve issues and learning from\n mistakes.\n\n_This code of conduct applies to all spaces managed by Rocket or the Rocket Web\nFramework Foundation including issues and discussions on GitHub, Matrix, and any\nother forums which the community uses for communication._\n\n_This Code of Conduct is adapted from the [Django Code of Conduct]. Original text\nfrom the [Speak Up! project]._\n\n[Django Code of Conduct]: https://www.djangoproject.com/conduct/\n[Speak Up! project]: http://web.archive.org/web/20141109123859/http://speakup.io/coc.html\n" }, { "path": ".github/FUNDING.yml", "content": "github: rwf2\nopen_collective: rwf2\n" }, { "path": ".github/ISSUE_TEMPLATE/bug-report.yml", "content": "name: Bug Report\ndescription: Report a functionality issue that deviates from the documentation.\nlabels: [\"triage\"]\nbody:\n - type: markdown\n attributes:\n value: >\n **Thanks for taking the time to fill out this bug report!** Your report\n helps make Rocket better.\n\n\n Please only report issues related to _functionality_ that deviates from\n published specification or reasonable expectation. Do not report issues\n with documentation, infrastructure, or anything unrelated to functional\n correctness here.\n - type: input\n attributes:\n label: Rocket Version\n description: >\n Enter the exact version of Rocket (x.y.z) or git shorthash (8d9dfce) you're using.\n\n\n Please ensure you're using the latest release before reporting a bug.\n placeholder: \"ex: 0.5.0\"\n validations:\n required: true\n - type: input\n attributes:\n label: Operating System\n description: Which operating system and version are you running?\n placeholder: \"examples: macOS 13.6.2, Arch Linux 4.16.13\"\n validations:\n required: true\n - type: input\n attributes:\n label: Rust Toolchain Version\n description: Which version of `rustc` are you using? (`rustc --version`)\n placeholder: \"ex: rustc 1.74.0 (79e9716c9 2023-11-13)\"\n validations:\n required: true\n - type: textarea\n attributes:\n label: What happened?\n description: Provide a brief overview of what went wrong.\n validations:\n required: true\n - type: textarea\n attributes:\n label: Test Case\n description: >\n Provide a Rocket application that elicits the bug. Ideally the program\n contains a `#[test]` case using Rocket's\n [`local`](https://api.rocket.rs/v0.5/rocket/local/index.html) testing\n module.\n placeholder: >\n #[macro_use] extern crate rocket;\n\n\n #[launch]\n\n fn rocket() -> _ {\n rocket::build()\n }\n\n\n #[test]\n\n fn failing_test() {\n use rocket::local::blocking::Client;\n\n let client = Client::tracked(rocket()).unwrap();\n let response = client.get(\"/\").dispatch();\n assert!(response.status().class().is_success());\n }\n render: rust\n validations:\n required: true\n - type: textarea\n attributes:\n label: Log Output\n description: >\n Please provide the complete log output captured with\n `ROCKET_LOG_LEVEL=debug` when the test case is run.\n placeholder: >\n ❯ ROCKET_LOG_LEVEL=debug cargo test\n\n running 1 test\n\n test failing_test ... FAILED\n\n failures:\n\n\n ---- failing_test stdout ----\n\n -- configuration trace information --\n >> \"address\" parameter source: rocket::Config::default()\n >> \"port\" parameter source: rocket::Config::default()\n >> \"workers\" parameter source: rocket::Config::default()\n >> \"max_blocking\" parameter source: rocket::Config::default()\n >> \"keep_alive\" parameter source: rocket::Config::default()\n >> \"ident\" parameter source: rocket::Config::default()\n >> \"ip_header\" parameter source: rocket::Config::default()\n >> \"limits\" parameter source: rocket::Config::default()\n >> \"temp_dir\" parameter source: rocket::Config::default()\n >> \"log_level\" parameter source: `ROCKET_` environment variable(s)\n >> \"shutdown\" parameter source: rocket::Config::default()\n >> \"cli_colors\" parameter source: rocket::Config::default()\n 🔧 Configured for debug.\n >> address: 127.0.0.1\n >> port: 8000\n [...]\n render: shell\n validations:\n required: true\n - type: textarea\n attributes:\n label: Additional Context\n description: >\n Feel free to provide any additional context for your bug report.\n - type: checkboxes\n attributes:\n label: System Checks\n description: \"Please confirm all of the following:\"\n options:\n - label: My bug report relates to functionality.\n required: true\n - label: I have tested against the latest Rocket release or a recent git commit.\n required: true\n - label: I have tested against the latest stable `rustc` toolchain.\n required: true\n - label: I was unable to find this issue previously reported.\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: true\ncontact_links:\n - name: FAQ\n url: https://rocket.rs/guide/faq/\n about: Please see our FAQ for answers to common questions.\n - name: Questions\n url: https://github.com/rwf2/Rocket/discussions/new?category=questions\n about: For other questions or help, please use GitHub discussions.\n - name: Feedback\n url: https://github.com/rwf2/Rocket/discussions/new/choose\n about: For general chat or feedback, please use GitHub discussions.\n - name: Chat\n url: https://chat.mozilla.org/#/room/#rocket:mozilla.org\n about: Chat with us live on rocket:mozilla.org on Matrix.\n" }, { "path": ".github/ISSUE_TEMPLATE/doc-problem.yml", "content": "name: Documentation Problem\ndescription: Report an issue with or suggest documentation.\nlabels: [\"docs\"]\nbody:\n - type: markdown\n attributes:\n value: >\n **Thanks for taking the time to report a documentation issue!**\n\n\n Documentation problems include everything from typos to missing or\n incorrect technical details in any of the following:\n - [Rocket's Website](https://rocket.rs/)\n - [The Rocket Programming Guide](https://rocket.rs/guide/)\n - [API Docs](https://api.rocket.rs)\n - [Content on GitHub](https://github.com/rwf2/Rocket)\n\n If we've written it, we want to know how it can be improved.\n - type: dropdown\n validations:\n required: true\n attributes:\n label: What kind of documentation problem are you reporting?\n multiple: true\n options:\n - Typo (PRs welcome!)\n - Unclear Docs\n - Undocumented Feature\n - Broken Links\n - Rendering Issue\n - Grammar Issue\n - Technical Problem\n - Other\n - type: input\n validations:\n required: true\n attributes:\n label: Where is the issue found?\n description: Please provide a direct link to the documentation.\n placeholder: \"ex: https://rocket.rs/v0.5/guide/requests/#multiple-segments\"\n - type: textarea\n validations:\n required: true\n attributes:\n label: What's wrong?\n description: >\n Please describe what's wrong with the documentation.\n - type: checkboxes\n attributes:\n label: System Checks\n description: \"Please confirm all of the following:\"\n options:\n - label: I confirmed that the issue still exists on `master` on GitHub.\n required: true\n - label: I was unable to find a previous report of this problem.\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/feature-request.yml", "content": "name: Feature Request\ndescription: Propose a change that introduces new functionality.\nlabels: [\"request\"]\nbody:\n - type: markdown\n attributes:\n value: >\n **Thanks for taking the time to request a feature!** Your request helps\n make Rocket better.\n\n\n Please note that Rocket is designed to have a small but pluggable core.\n Feature requests that can be implemented outside of Rocket _are\n typically declined._ In your request, please make a strong case for why\n this feature can't or shouldn't be implemented outside of Rocket.\n - type: textarea\n attributes:\n label: What's missing?\n description: >\n Provide a brief overview of the functionality that's missing in Rocket\n today, which problem(s) that functionality would solve for you, and what\n the functionality would enable you to do.\n placeholder: >\n example: I frequently want to do X, but Rocket makes it hard. It would\n be nice if Rocket...\n\n example: I want to do X but Rocket makes it impossible because...\n\n example: Feature Z exists, but it has these N drawbacks: [..]. What if...\n validations:\n required: true\n - type: textarea\n attributes:\n label: Ideal Solution\n description: >\n If you already have an idea of how this feature can be implemented,\n please describe it here. Hypothetical code examples are particularly\n useful.\n - type: textarea\n attributes:\n label: Why can't this be implemented outside of Rocket?\n description: >\n Please make a strong case for why this feature can't or shouldn't be\n implemented outside of Rocket. We are likely to decline feature requests\n that can exist outside of Rocket without compromise.\n validations:\n required: true\n - type: textarea\n attributes:\n label: Are there workarounds usable today?\n description: >\n If the functionality being requested can be achieved today, please detail\n how here.\n - type: textarea\n attributes:\n label: Alternative Solutions\n description: >\n If you have other ideas about how this feature can be implemented, let\n us know.\n - type: textarea\n attributes:\n label: Additional Context\n description: >\n Feel free to provide any additional context for your request.\n - type: checkboxes\n attributes:\n label: System Checks\n description: \"Please confirm all of the following:\"\n options:\n - label: I do not believe that this feature can or should be implemented outside of Rocket.\n required: true\n - label: I was unable to find a previous request for this feature.\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/suggestion.yml", "content": "name: Suggestion\ndescription: Suggest a change or improvement to existing functionality.\nlabels: [\"suggestion\"]\nbody:\n - type: markdown\n attributes:\n value: >\n **Thanks for taking the time to make a suggestion!**\n - type: input\n validations:\n required: true\n attributes:\n label: API Docs to Existing Functionality\n description: Please provide a direct link to the API docs for the\n functionality you'd like to change.\n placeholder: \"ex: https://api.rocket.rs/v0.5/rocket/trait.Sentinel.html\"\n - type: textarea\n validations:\n required: true\n attributes:\n label: Problems with Existing Functionality\n description: Please let us know what you think is wrong with the existing functionality.\n placeholder: >\n example: Sentinels don't allow me to access `Foo`, but I'd like to because...\n\n example: Feature Z exists, but it has these drawbacks. What if...\n - type: textarea\n validations:\n required: true\n attributes:\n label: Suggested Changes\n description: >\n How do you propose the existing functionality be changed? Code examples\n are particular useful.\n - type: textarea\n validations:\n required: true\n attributes:\n label: Alternatives Considered\n description: >\n Instead of making a change to Rocket, please describe alternative\n solutions using existing features or new features you've considered.\n - type: textarea\n attributes:\n label: Additional Context\n description: Feel free to provide any additional context for your suggestion.\n - type: checkboxes\n attributes:\n label: System Checks\n description: \"Please confirm all of the following:\"\n options:\n - label: >\n I do not believe that this suggestion can or should be implemented\n outside of Rocket.\n required: true\n - label: I was unable to find a previous suggestion for this change.\n required: true\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non: [push, pull_request]\n\nenv:\n CARGO_TERM_COLOR: always\n\njobs:\n test:\n name: \"${{ matrix.platform.name }} ${{ matrix.test.name }} (${{ matrix.platform.toolchain }})\"\n runs-on: ${{ matrix.platform.distro }}\n\n strategy:\n fail-fast: false\n matrix:\n platform:\n - { name: Linux, distro: ubuntu-latest, toolchain: stable }\n - { name: Windows, distro: windows-latest, toolchain: stable }\n - { name: macOS, distro: macOS-latest, toolchain: stable }\n - { name: Linux, distro: ubuntu-latest, toolchain: nightly }\n test:\n - { name: Debug }\n - { name: Examples, flag: \"--examples\" }\n - { name: Contrib, flag: \"--contrib\" }\n include:\n # Additional tests on Linux/stable.\n - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable }\n test: { name: Core, flag: \"--core\" }\n - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable }\n test: { name: Release, flag: \"--release\" }\n - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable }\n test: { name: Testbench, flag: \"--testbench\" }\n - platform: { name: Linux, distro: ubuntu-latest, toolchain: stable }\n test: { name: UI, flag: \"--ui\" }\n fallible: true\n # Allow tests on nightly to fail.\n - platform: { toolchain: nightly }\n fallible: true\n # Use the bigger 'C:/' from the \"Switch Disk\" step\n - platform: { name: Windows }\n working-directory:\n \"C:\\\\a\\\\${{ github.event.repository.name }}\\\\${{ github.event.repository.name }}\"\n\n steps:\n - name: Checkout Sources\n uses: actions/checkout@v4\n\n - name: Free Disk Space (Linux)\n if: matrix.platform.name == 'Linux'\n run: |\n echo \"Freeing up disk space on Linux CI\"\n df -h\n sudo rm -rf /usr/share/dotnet/\n sudo rm -rf /opt/ghc\n sudo rm -rf /usr/local/share/boost\n sudo rm -rf /usr/local/graalvm/\n sudo rm -rf /usr/local/.ghcup/\n sudo rm -rf /usr/local/share/powershell\n sudo rm -rf /usr/local/share/chromium\n sudo rm -rf /usr/local/lib/android\n sudo rm -rf /usr/local/lib/node_modules\n sudo rm -rf \"$AGENT_TOOLSDIRECTORY\"\n sudo docker image prune --all --force\n df -h\n\n - name: Install Native Dependencies (macOS)\n if: matrix.platform.name == 'macOS'\n run: |\n brew install mysql-client@8.4 libpq sqlite coreutils\n brew link --force --overwrite mysql-client@8.4\n brew link --force --overwrite libpq\n echo \"/usr/local/opt/mysql-client/bin\" >> \"$GITHUB_PATH\"\n\n # vcpkg --triplet x64-windows install libmysql libpq sqlite3 openssl\n # + vcpkg/installed/vcpkg (in particular, the status file)\n - name: Install Native Dependencies (Windows)\n if: matrix.platform.name == 'Windows'\n run: |\n curl -fsLS -o vcpkg.7z https://blob.rocket.rs/vcpkg-2024-08-16.7z\n 7z x vcpkg.7z -y -bb0\n xcopy .\\vcpkg $env:VCPKG_INSTALLATION_ROOT /s /e /h /y /q\n vcpkg integrate install\n echo \"VCPKGRS_DYNAMIC=1\" >> \"$env:GITHUB_ENV\"\n echo \"VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT\" >> \"$env:GITHUB_ENV\"\n echo \"$env:VCPKG_INSTALLATION_ROOT\\installed\\x64-windows\\lib\" >> \"$env:GITHUB_PATH\"\n echo \"MYSQLCLIENT_VERSION=8.0.39\" >> \"$env:GITHUB_ENV\"\n\n - name: Install NASM (Windows)\n if: matrix.platform.name == 'Windows'\n uses: ilammy/setup-nasm@v1\n\n - name: Install Native Dependencies (Linux)\n if: matrix.platform.name == 'Linux'\n run: |\n sudo apt-get update\n sudo apt-get install -y libmysqlclient-dev libpq-dev libsqlite3-dev\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@master\n id: toolchain\n with:\n toolchain: ${{ matrix.platform.toolchain }}\n components: rust-src\n\n - name: Cache Example Workspace\n if: matrix.test.name == 'Examples'\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: examples\n key: ${{ matrix.test.name }}-${{ steps.toolchain.outputs.cachekey }}\n\n - name: Cache Root Workspace\n if: matrix.test.name != 'Examples'\n uses: Swatinem/rust-cache@v2\n with:\n key: ${{ matrix.test.name }}-${{ steps.toolchain.outputs.cachekey }}\n\n # Don't run out of disk space on Windows. C: has much much space than D:.\n - name: Switch Disk (Windows)\n if: matrix.platform.name == 'Windows'\n run: |\n Get-PSDrive\n cp D:\\a C:\\ -Recurse\n Get-PSDrive\n\n - name: Run Tests\n continue-on-error: ${{ matrix.fallible || false }}\n working-directory: ${{ matrix.working-directory || github.workspace }}\n run: ./scripts/test.sh ${{ matrix.test.flag || '' }} -q\n shell: bash\n" }, { "path": ".github/workflows/trigger.yaml", "content": "name: Trigger\non: [push]\njobs:\n trigger:\n name: api.rocket.rs\n runs-on: ubuntu-latest\n if: github.repository == 'rwf2/Rocket'\n steps:\n - uses: actions/github-script@v7\n with:\n github-token: ${{ secrets.API_DOCS_DEPLOY_TOKEN }}\n script: |\n github.rest.actions.createWorkflowDispatch({\n owner: 'rwf2',\n repo: 'api.rocket.rs',\n workflow_id: 'deploy.yaml',\n ref: 'master'\n })\n" }, { "path": ".gitignore", "content": "# Compiled files\n*.o\n*.so\n*.rlib\n*.dll\n\n# Executables\n*.exe\n\n# Generated by Cargo\ntarget\n\n# Generated databases\ndb.sqlite\ndb.sqlite-shm\ndb.sqlite-wal\n\n# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries\n# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html\nCargo.lock\n\n# Cargo config directory\n.cargo/\n\n# The upload script, for now.\nscripts/upload-docs.sh\nscripts/redirect.html\n\n# Backup files.\n*.bak\n\n# Uploads in pastebin example.\nexamples/pastebin/upload/*\n" }, { "path": ".rustfmt.toml", "content": "disable_all_formatting = true\n" }, { "path": "CHANGELOG.md", "content": "# Version 0.5.1 (May 22, 2024)\n\nThis release contains the following crate updates:\n\n - `rocket` `0.5.1`\n - `rocket_db_pools` `0.2.0`\n - `rocket_dyn_templates` `0.2.0`\n - `rocket_ws` `0.1.1`\n\n## [`rocket`](https://api.rocket.rs/v0.5/rocket/) `0.5.1`\n\n * The following `char` and `std::ops::Range` types now implement `FromForm`:\n\n - `char`\n - `Range` with `start` and `end` fields\n - `RangeFrom` with `start` field\n - `RangeTo` with `end` field\n - `RangeToInclusive` with `end` field\n\n * `[T; N]`, `Vec`, and `[u8]` can now be passed to `uri!`.\n\n * The guide now includes a [deploying section].\n\n * The `FromForm` derive now properly records errors involving entire forms.\n\n * `FromForm` derive can now be used in code emitted by `macro_rules!` macros.\n\n * **(fix [#2668] via [52de9a])** [`TempFile`] now ensures it flushes before\n being persisted.\n\n## [`rocket_db_pools`](https://api.rocket.rs/v0.5/rocket_db_pools/) `0.2.0`\n\n * SQLite extensions are now supported in `sqlx_sqlite`.\n\n Use a database configuration option of `extensions` to specify extensions:\n\n ```toml\n [default.databases.db_name]\n url = \"db.sqlite\"\n # This option is only supported by the `sqlx_sqlite` driver.\n extensions = [\"memvfs\", \"rot13\"]\n ```\n\n * (**breaking**) `deadpool` was updated to `0.13`.\n\n * (**breaking**) The [`Config`](https://api.rocket.rs/v0.5/rocket_db_pools/struct.Config)\n structure has a new `extensions` field.\n\n## [`rocket_dyn_templates`](https://api.rocket.rs/v0.5/rocket_dyn_templates/) `0.2.0`\n\n * Support for `minijinja` `2.0` templates was introduced.\n\n Templates with an extension of `.j2` are recognized and rendered with\n Minijinja.\n\n * **(breaking)** `handlebars` was updated to `5.1`.\n\n## [`rocket_ws`](https://api.rocket.rs/v0.5/rocket_ws/) `0.1.1`\n\n * Introduced [`WebSocket::accept_key()`] method.\n\n * `tungstenite` was updated to `0.21`.\n\n## General Changes\n\n * The `rust-version` for all crates was updated to `1.64`.\n\n This reflects the correct MSRV required to build `rocket` `0.5.0`.\n\n * License files are now present in all published crates.\n\n[52de9a]: https://github.com/rwf2/Rocket/commit/52de9a\n[#2668]: https://github.com/rwf2/Rocket/pull/2668\n[deploying section]: https://rocket.rs/guide/v0.5/deploying/\n[`WebSocket::accept_key()`]: https://api.rocket.rs/v0.5/rocket_ws/struct.WebSocket#method.accept_key\n\n# Version 0.5.0 (Nov 17, 2023)\n\n## Major Features and Improvements\n\nThis release introduces the following major features and improvements:\n\n * Support for [compilation on Rust's stable] release channel.\n * A rewritten, fully asynchronous core with support for [`async`/`await`].\n * WebSocket support via [`rocket_ws`].\n * [Feature-complete forms support] including multipart, collections, [ad-hoc validation], and\n [context](https://rocket.rs/v0.5/guide/requests/#context).\n * [Sentinels]: automatic verification of application state at start-up to prevent runtime errors.\n * [Graceful shutdown] with configurable signaling, grace periods, [notification], and\n [shutdown fairings].\n * An entirely new, flexible and robust [configuration system] based on [Figment].\n * Typed [asynchronous streams] and [Server-Sent Events] with generator syntax.\n * Asynchronous database pooling support via [`rocket_db_pools`].\n * Support for [mutual TLS] and client [`Certificate`]s.\n * Automatic support for HTTP/2 including `h2` ALPN.\n * Graduation of `json`, `msgpack`, and `uuid` `rocket_contrib` [features into core].\n * An automatically enabled [`Shield`]: security and privacy headers for all responses.\n * Type-system enforced [incoming data limits] to mitigate memory-based DoS attacks.\n * Compile-time URI literals via a fully revamped [`uri!`] macro.\n * [Request connection upgrade APIs] with support for raw I/O with the client.\n * Full support for [UTF-8 characters] in routes and catchers.\n * Precise detection of missing managed state, databases, and templating with [sentinels].\n * Typed [build phases] with strict application-level guarantees.\n * [Ignorable segments]: wildcard route matching with no typing restrictions.\n * First-class [support for `serde`] for built-in guards and types.\n * New application launch attributes:\n [`#[launch]`](https://api.rocket.rs/v0.5/rocket/attr.launch.html) and\n [`#[rocket::main]`](https://api.rocket.rs/v0.5/rocket/attr.main.html).\n * [Default catchers] via `#[catch(default)]`, which handle _any_ status code.\n * [Catcher scoping] to narrow the scope of a catcher to a URI prefix.\n * Built-in libraries and support for [asynchronous testing].\n * A [`TempFile`] data and form guard for automatic uploading to a temporary file.\n * A [`Capped`] data and form guard which enables detecting truncation due to data limits.\n * Support for dynamic and static prefixing and suffixing of route URIs in [`uri!`].\n * Support for custom config profiles and [automatic typed config extraction].\n * Rewritten, zero-copy, RFC compliant URI parsers with support for URI-[`Reference`]s.\n * Multi-segment parameters (``) which match _zero_ segments.\n * A [`local_cache!`] macro for request-local storage of non-uniquely typed values.\n * A [`CookieJar`] without \"one-at-a-time\" limitations.\n * [Singleton fairings] with replacement and guaranteed uniqueness.\n * [Data limit declaration in SI units]: \"2 MiB\", `2.mebibytes()`.\n * Optimistic responding even when data is left unread or limits are exceeded.\n * Fully decoded borrowed strings as dynamic parameters, form and data guards.\n * Borrowed byte slices as data and form guards.\n * Fail-fast behavior for [misconfigured secrets], file serving paths.\n * Support for generics and custom generic bounds in\n [`#[derive(Responder)]`](https://api.rocket.rs/v0.5/rocket/derive.Responder.html).\n * [Default ranking colors], which prevent more routing collisions automatically.\n * Improved error logging with suggestions when common errors are detected.\n * Completely rewritten examples including a new real-time [`chat`] application.\n\n## Support for Rust Stable\n\nAs a result of support for Rust stable (Rust 2021 Edition and beyond),\n`#![feature(..)]` crate attributes are no longer required to use Rocket. The\ncomplete canonical example with a single `hello` route becomes:\n\n```rust\n#[macro_use] extern crate rocket;\n\n#[get(\"//\")]\nfn hello(name: &str, age: u8) -> String {\n format!(\"Hello, {} year old named {}!\", age, name)\n}\n\n#[launch]\nfn rocket() -> _ {\n rocket::build().mount(\"/hello\", routes![hello])\n}\n```\n\n
\n See a diff of the changes from v0.4.\n\n```diff\n- #![feature(proc_macro_hygiene, decl_macro)]\n-\n #[macro_use] extern crate rocket;\n\n #[get(\"//\")]\n- fn hello(name: String, age: u8) -> String {\n+ fn hello(name: &str, age: u8) -> String {\n format!(\"Hello, {} year old named {}!\", age, name)\n}\n\n- fn main() {\n- rocket::ignite().mount(\"/hello\", routes![hello]).launch();\n- }\n+ #[launch]\n+ fn rocket() -> _ {\n+ rocket::build().mount(\"/hello\", routes![hello])\n+ }\n```\n\n
\n\n## Breaking Changes\n\nThis release includes many breaking changes. For a walkthrough guide on handling these changes, see\nthe [v0.4 to v0.5 migration guide]. The most significant changes are listed below.\n\n### Silent Changes\n\nThese changes are invisible to the compiler and will _not_ yield errors or warnings at compile-time.\nWe **strongly** advise all application authors to review this list carefully.\n\n * Blocking I/O (long running compute, synchronous `sleep()`, `Mutex`, `RwLock`, etc.) may prevent\n the server from making progress and should be avoided, replaced with an `async` variant, or\n performed in a worker thread. This is a consequence of Rust's cooperative `async` multitasking.\n For details, see the new [multitasking] section of the guide.\n * `ROCKET_ENV` is now `ROCKET_PROFILE`. A warning is emitted a launch time if the former is set.\n * The default profile for debug builds is now `debug`, not `dev`.\n * The default profile for release builds is now `release`, not `prod`.\n * `ROCKET_LOG` is now `ROCKET_LOG_LEVEL`. A warning is emitted a launch time if the former is set.\n * `ROCKET_ADDRESS` accepts only IP addresses, no longer resolves hostnames like `localhost`.\n * `ROCKET_CLI_COLORS` accepts booleans `true`, `false` in place of strings `\"on\"`, `\"off\"`.\n * It is a launch-time error if `secrets` is enabled in non-`debug` profiles without a configured\n `secret_key`.\n * A misconfigured `template_dir` is reported as an error at launch time.\n * [`FileServer::new()`] fails immediately if the provided directory does not exist.\n * Catcher collisions result in a launch failure as opposed to a warning.\n * Default ranks now range from `-12` to `-1`. There is no breaking change if only code generated\n routes are used. Manually configured routes with negative ranks may collide or be considered in\n a different order than before.\n * The order of execution of path and query guards relative to each other is now unspecified.\n * URIs beginning with `:` are properly recognized as invalid and rejected.\n * URI normalization now normalizes the query part as well.\n * The `Segments` iterator now returns percent-decoded `&str`s.\n * Forms are now parsed leniently by the [`Form` guard]. Use [`Strict`] for the previous behavior.\n * The `Option` form guard defaults to `None` instead of the default value for `T`.\n * When data limits are exceeded, a `413 Payload Too Large` status is returned to the client.\n * The default catcher now returns JSON when the client indicates preference via the `Accept`\n header.\n * Empty boolean form values parse as `true`: the query string `?f` is the same as `?f=true`.\n * [`Created`] does not automatically send an `ETag` header if `R: Hash`. Use\n [`Created::tagged_body`] instead.\n * `FileServer` now forwards when a file is not found instead of failing with `404 Not Found`.\n * [`Shield`] is enabled by default. You may need to disable or change policies if your application\n depends on typically insecure browser features or if you wish to opt-in to different policies\n than the defaults.\n * [`CookieJar`] `get()`s do not return cookies added during request handling. See\n [`CookieJar`#pending].\n * `Hash` `impl`s for `MediaType` and `ContentType` no longer consider media type parameters.\n * When requested, the `FromForm` implementations of `Vec` and `Map`s are now properly lenient.\n * To agree with browsers, the `[` and `]` characters are now accepted in URI paths.\n * The `[` and `]` characters are no longer encoded by [`uri!`].\n * The `Secure` cookie flag is set by default for all cookies when serving over TLS.\n * Removal cookies have `SameSite` set to `Lax` by default.\n * [`MediaType::JavaScript`] is now `text/javascript`.\n\n### Contrib Graduation\n\nThe `rocket_contrib` crate is deprecated and the functionality moved to other `rocket` crates. The\n[contrib deprecation upgrade guide] provides a walkthrough on migrating. The relevant changes are:\n\n * Several features previously in `rocket_contrib` were merged into `rocket` itself:\n - `json`, `msgpack`, and `uuid` are now [features of `rocket`].\n - Moved `rocket_contrib::json` to [`rocket::serde::json`].\n - Moved `rocket_contrib::msgpack` to [`rocket::serde::msgpack`].\n - Moved `rocket_contrib::uuid` to [`rocket::serde::uuid`].\n - Moved `rocket_contrib::helmet` to [`rocket::shield`]. [`Shield`] is enabled by default.\n - Moved `rocket_contrib::serve` to [`rocket::fs`], `StaticFiles` to [`rocket::fs::FileServer`].\n - Removed the now unnecessary `Uuid` and `JsonValue` wrapper types.\n - Removed headers in `Shield` that are no longer respected by browsers.\n * The remaining features from `rocket_contrib` are now provided by separate crates:\n - Replaced `rocket_contrib::templates` with [`rocket_dyn_templates`].\n - Replaced `rocket_contrib::databases` with [`rocket_sync_db_pools`] and [`rocket_db_pools`].\n - These crates are versioned and released independently of `rocket`.\n - `rocket_contrib::databases::DbError` is now `rocket_sync_db_pools::Error`.\n - Removed `redis`, `mongodb`, and `mysql` integrations which have upstream `async` drivers.\n - The [`#[database]`](https://api.rocket.rs/v0.5/rocket_sync_db_pools/attr.database.html)\n attribute generates an [`async run()`] method instead of `Deref` implementations.\n\n### General\n\nThe following breaking changes apply broadly and are likely to cause compile-time errors.\n\n * [`Rocket`] is now generic over a [phase] marker:\n - APIs operate on `Rocket`, `Rocket`, `Rocket`, or `Rocket` as\n needed.\n - The phase marker statically enforces state transitions in `Build`, `Ignite`, `Orbit` order.\n - `rocket::ignite()` is now [`rocket::build()`] and returns a `Rocket`.\n - [`Rocket::ignite()`] transitions to the `Ignite` phase. This is run automatically on launch as\n needed.\n - Ignition finalizes configuration, runs `ignite` fairings, and verifies [sentinels].\n - [`Rocket::launch()`] transitions into the `Orbit` phase and starts the server.\n - Methods like [`Request::rocket()`] that refer to a live Rocket instance return an\n `&Rocket`.\n * [Fairings] have been reorganized and restructured for `async`:\n - Replaced `attach` fairings with `ignite` fairings. Unlike `attach` fairings, which ran\n immediately at the time of attachment, `ignite` fairings are run when transitioning into the\n `Ignite` phase.\n - Replaced `launch` fairings with `liftoff` fairings. `liftoff` fairings are always run, even in\n local clients, after the server begins listening and the concrete port is known.\n * Introduced a new [configuration system] based on [Figment]:\n - The concept of \"environments\" is replaced with \"profiles\".\n - `ROCKET_ENV` is superseded by `ROCKET_PROFILE`.\n - `ROCKET_LOG` is superseded by `ROCKET_LOG_LEVEL`.\n - Profile names can now be arbitrarily chosen. The `dev`, `stage`, and `prod` profiles carry no\n special meaning.\n - The `debug` and `release` profiles are the default profiles for the debug and release\n compilation profiles.\n - A new specially recognized `default` profile specifies defaults for all profiles.\n - The `global` profile has highest precedence, followed by the selected profile, followed by\n `default`.\n - Added support for limits specified in SI units: \"1 MiB\".\n - Renamed `LoggingLevel` to [`LogLevel`].\n - Inlined error variants into the [`Error`] structure.\n - Changed the type of `workers` to `usize` from `u16`.\n - Changed accepted values for `keep_alive`: it is disabled with `0`, not `false` or `off`.\n - Disabled the `secrets` feature (for private cookies) by default.\n - Removed APIs related to \"extras\". Typed values can be extracted from the configured `Figment`.\n - Removed `ConfigBuilder`: all fields of [`Config`] are public with constructors for each field\n type.\n * Many functions, traits, and trait bounds have been modified for `async`:\n - [`FromRequest`], [`Fairing`], [`catcher::Handler`], [`route::Handler`], and [`FromData`] use\n `#[async_trait]`.\n - [`NamedFile::open`] is now an `async` function.\n - Added [`Request::local_cache_async()`] for use in async request guards.\n - Unsized `Response` bodies must be [`AsyncRead`] instead of `Read`.\n - Automatically sized `Response` bodies must be [`AsyncSeek`] instead of `Seek`.\n - The `local` module is split into two: [`rocket::local::asynchronous`] and\n [`rocket::local::blocking`].\n * Functionality and features requiring Rust nightly were removed:\n - Removed the `Try` implementation on [`Outcome`] which allowed using `?` with `Outcome`s. The\n recommended replacement is the [`rocket::outcome::try_outcome!`] macro or the various\n combinator functions on `Outcome`.\n - [`Result` implements `Responder`] only when both `T` and `E` implement `Responder`. The\n new [`Debug`] wrapping responder replaces `Result`.\n - APIs which used the `!` type to now use [`std::convert::Infallible`].\n * [`IntoOutcome`] was overhauled to supplant methods now removed in `Outcome`.\n - `IntoOutcome::into_outcome()` is now `or_error()`.\n - `IntoOutcome` is implemented for all `Outcome` type aliases.\n - `Outcome::forward()` requires specifying a status code.\n - `Outcome::from()` and `Outcome::from_or_forward()` were removed.\n * [`Rocket::register()`] now takes a base path to scope catchers under as its first argument.\n * `ErrorKind::Collision` has been renamed to [`ErrorKind::Collisions`].\n * TLS config values are only available when the `tls` feature is enabled.\n * [`MediaType::with_params()`] and [`ContentType::with_params()`] are now builder methods.\n * Content-Type [`content`] responder type names are now prefixed with `Raw`.\n * The `content::Plain` responder is now called `content::RawText`.\n * The `content::Custom` responder was removed in favor of [`(ContentType, T)`].\n * Removed `CookieJar::get_private_pending()` in favor of [`CookieJar::get_pending()`].\n * The [`local_cache!`] macro accepts fewer types. Use [`local_cache_once!`] as appropriate.\n * [`Rocket::launch()`] allows `Rocket` recovery by returning the instance after shutdown.\n * `ErrorKind::Runtime` was removed; [`ErrorKind::Shutdown`] was added.\n * `Outcome::Failure` was renamed to [`Outcome::Error`].\n\n### Routing and URIs\n\n * In `#[route(GET, path = \"...\")]`, `path` is now `uri`: `#[route(GET, uri = \"...\")]`.\n * Multi-segment paths (`/`) now match _zero_ or more segments.\n * Codegen improvements preclude identically named routes and modules in the same namespace.\n * A route URI like (`//`) now collides with (`/`), requires a `rank` to resolve.\n * All catcher related types and traits moved to [`rocket::catcher`].\n * All route related types and traits moved to [`rocket::route`].\n * URI formatting types and traits moved to [`rocket::http::uri::fmt`].\n * `T` no longer converts to `Option` or `Result` for [`uri!`] query parameters.\n * For optional query parameters, [`uri!`] requires using a wrapped value or `_`.\n * `&RawStr` no longer implements `FromParam`: use `&str` instead.\n * Percent-decoding is performed before calling `FromParam` implementations.\n * `RawStr::url_decode()` and `RawStr::url_decode_lossy()` allocate as necessary, return `Cow`.\n * `RawStr::from_str()` was replaced with `RawStr::new()`.\n * `Origin::segments()` was replaced with `Origin.path().segments()`.\n * `Origin::path()` and `Origin::query()` return `&RawStr` instead of `&str`.\n * The type of `Route::name` is now `Option>`.\n * `Route::set_uri` was replaced with [`Route::map_base()`].\n * The `Route::uri` field is now of type [`RouteUri`].\n * `Route::base` was removed in favor of `Route.uri().base()`.\n * [Route `Forward` outcomes] are now associated with a `Status`.\n * The status codes used when built-in guards forward were changed:\n - Route parameter `FromParam` errors now forward as 422.\n - Query parameter errors now forward as 422.\n - Incorrect form content-type errors forwards as 413.\n - `&Host`, `&Accept`, `&ContentType`, `IpAddr`, and `SocketAddr` all forward\n with a 500.\n\n### Data and Forms\n\n * `Data` now has a lifetime generic: `Data<'r>`.\n * [`Data::open()`] indelibly requires a data limit.\n * Removed `FromDataSimple`. Use [`FromData`] and [`local_cache!`] or [`local_cache_once!`].\n * All [`DataStream`] APIs require limits and return [`Capped`] types.\n * Form types and traits were moved from `rocket::request` to [`rocket::form`].\n * Removed `FromQuery`. Dynamic query parameters (`#[get(\"/?\")]`) use [`FromForm`] instead.\n * Replaced `FromFormValue` with [`FromFormField`]. All `T: FromFormField` implement `FromForm`.\n * Form field values are percent-decoded before calling [`FromFormField`] implementations.\n * Renamed the `#[form(field = ...)]` attribute to `#[field(name = ...)]`.\n * [Custom form errors] must now specify an associated `Status`.\n\n### Request Guards\n\n * Renamed `Cookies` to [`CookieJar`]. Its methods take `&self`.\n * Renamed `Flash.name` to `Flash.kind`, `Flash.msg` to `Flash.message`.\n * Replaced `Request::get_param()` with `Request::param()`.\n * Replaced `Request::get_segments()` to `Request::segments()`.\n * Replaced `Request::get_query_value()` with `Request::query_value()`.\n * Replaced `Segments::into_path_buf()` with `Segments::to_path_buf()`.\n * Replaced `Segments` and `QuerySegments` with [`Segments` and `Segments`].\n * [`Flash`] constructors now take `Into` instead of `AsRef`.\n * The `State<'_, T>` request guard is now `&State`.\n * Removed a lifetime from [`FromRequest`]: `FromRequest<'r>`.\n * Removed a lifetime from [`FlashMessage`]: `FlashMessage<'_>`.\n * Removed all `State` reexports except [`rocket::State`].\n\n### Responders\n\n * Moved `NamedFile` to `rocket::fs::NamedFile`\n * Replaced `Content` with `content::Custom`.\n * `Response::body` and `Response::body_mut` are now infallible methods.\n * Renamed `ResponseBuilder` to `Builder`.\n * Removed direct `Response` body reading methods. Use methods on `r.body_mut()` instead.\n * Removed inaccurate \"chunked body\" types and variants.\n * Removed `Responder` `impl` for `Response`. Prefer custom responders with `#[derive(Responder)]`.\n * Removed the unused reason phrase from `Status`.\n * The types of responders in [`response::status`] were unified to all be of\n the form `Status(R)`.\n\n## General Improvements\n\nIn addition to new features and changes, Rocket saw the following improvements:\n\n### General\n\n * Added support for [raw identifiers] in the `FromForm` derive, `#[route]` macros, and `uri!`.\n * Added support for uncased derived form fields: `#[field(name = uncased(...))]`.\n * Added support for [default form field values]: `#[field(default = expr())]`.\n * Added support for multiple `#[field]` attributes on struct fields.\n * Added support for base16-encoded (a.k.a. hex-encoded) secret keys.\n * Added [`Config::ident`] for configuring or removing the global `Server` header.\n * Added [`Rocket::figment()`] and [`Rocket::catchers()`].\n * Added [`LocalRequest::json()`] and [`LocalResponse::json()`].\n * Added [`LocalRequest::msgpack()`] and [`LocalResponse::msgpack()`].\n * Added support for `use m::route; routes![route]` instead of needing `routes![m::route]`.\n * Added support for [hierarchical data limits]: a limit of `a/b/c` falls back to `a/b` then `a`.\n * Added [`LocalRequest::inner_mut()`]. `LocalRequest` implements `DerefMut` to `Request`.\n * Added support for ECDSA and EdDSA TLS keys.\n * Added associated constants in `Config` for all config parameter names.\n * Added `ErrorKind::Config` to represent errors in configuration at runtime.\n * Added `rocket::fairing::Result` type alias, returned by `Fairing::on_ignite()`.\n * All guard failures are logged at runtime.\n * `Rocket::mount()` now accepts a base value of any type that implements `TryInto>`.\n * The default error catcher's HTML has been compacted.\n * The default error catcher returns JSON if requested by the client.\n * Panics in routes or catchers are caught and forwarded to `500` error catcher.\n * A detailed warning is emitted if a route or catcher panics.\n * Emoji characters are no longer output on Windows.\n * Fixed [`Error`] to not panic if a panic is already in progress.\n * Introduced [`Reference`] and [`Asterisk`] URI types.\n * Added support to [`UriDisplayQuery`] for C-like enums.\n * The [`UriDisplayQuery`] derive now recognizes the `#[field]` attribute for field renaming.\n * `Client` method builders accept `TryInto` allowing a `uri!()` to be used directly.\n * [`Rocket`] is now `#[must_use]`.\n * Support for HTTP/2 can be disabled by disabling the default `http2` crate feature.\n * Added [`rocket::execute()`] for executing Rocket's `launch()` future.\n * Added the [`context!`] macro to [`rocket_dyn_templates`] for ad-hoc template contexts.\n * The `time` crate is re-exported from the crate root.\n * The `FromForm`, `Responder`, and `UriDisplay` derives now fully support generics.\n * Added helper functions to `serde` submodules.\n * The [`Shield`] HSTS preload header now includes `includeSubdomains`.\n * Logging ignores `write!` errors if `stdout` disappears, preventing panics.\n * Added [`Client::terminate()`] to run graceful shutdown in testing.\n * Shutdown now terminates the `async` runtime, never the process.\n * Added a [`local_cache_once!`] macro for request-local storage.\n * Final launch messages are now _always_ logged, irrespective of profile.\n * Only functions that return `Rocket` are now `#[must_use]`, not all `Rocket

`.\n * Fixed mismatched form field names in errors under certain conditions in [`FromForm`] derive.\n * The [`FromForm`] derive now collects _all_ errors that occur.\n * Data pools are now gracefully shutdown in [`rocket_sync_db_pools`].\n * Added [`Metadata::render()`] in [`rocket_dyn_templates`] for direct template rendering.\n * Rocket salvages more information from malformed requests for error catchers.\n * The `cookie` `secure` feature is now properly conditionally enabled.\n * Data before encapsulation boundaries in TLS keys is allowed and ignored.\n * Support for TLS keys in SEC1 format was added.\n * Rocket now warns when a known secret key is configured.\n * A panic that could occur on shutdown in `rocket_sync_db_pools` was fixed.\n * Added a [`max_blocking`] configuration parameter to control number of blocking threads.\n * Added an [`ip_header`] \"real IP\" header configuration parameter.\n * A [`pool()`] method is emitted by [`rocket_sync_db_pools`] for code-generated pools.\n * Data guards are now eligible [sentinels].\n * Raw binary form field data can be retrieved using the `&[u8]` form guard.\n * Added [`TempFile::open()`] to stream `TempFile` data.\n * mTLS certificates can be set on local requests with [`LocalRequest::identity()`].\n * Added [`Error::pretty_print()`] for pretty-printing errors like Rocket.\n * Warnings are logged when data limits are reached.\n * A warning is emitted when `String` is used as a route parameter.\n * Configuration provenance information is logged under the `debug` log level.\n * Logging of `Outcome`s now includes the relevant status code.\n * `Span::mixed_site()` is used in codegen to reduce errant `clippy` warnings.\n\n### HTTP\n\n * Added support for HTTP/2, enabled by default via the `http2` crate feature.\n * Added a `const` constructor for `MediaType`.\n * Introduced [`RawStrBuf`], an owned `RawStr`.\n * Added many new \"pattern\" methods to [`RawStr`].\n * Added [`RawStr::percent_encode()`] and [`RawStr::strip()`].\n * Added support for unencoded query characters in URIs that are frequently sent by browsers.\n * Introduced [`Host`] and [`&Host`] request guards.\n * Added [`RawStr::percent_encode_bytes()`].\n * `NODELAY` is now enabled on all connections by default.\n * The TLS implementation handles handshakes off the main task, improving DoS resistance.\n\n### Known Media Types\n\n * Added AVIF: `image/avif`.\n * Added `EventStream`: `text/event-stream`.\n * Added `Markdown`: `text/markdown`.\n * Added `MP3`: `audio/mpeg`.\n * Added `CBZ`: `application/vnd.comicbook+zip`, extension `.cbz`.\n * Added `CBR`: `application/vnd.comicbook-rar`, extension `.cbr`.\n * Added `RAR`: `application/vnd.rar`, extension `.rar`.\n * Added `EPUB`: `application/epub+zip`, extension `.epub`.\n * Added `OPF`: `application/oebps-package+xml`, extension `.opf`.\n * Added `XHTML`: `application/xhtml+xml`, extension `.xhtml`.\n * Added `Text` as an alias for the `Plain` media type.\n * Added `Bytes` as an alias for the `Binary` media type.\n * Added `.mjs` as known JavaScript extension.\n * Added '.exe', '.iso', '.dmg' as known extensions.\n\n### Request\n\n * Added support for all UTF-8 characters in route paths.\n * Added support for percent-encoded `:` in socket or IP address values in [`FromFormValue`].\n * Added [`Request::rocket()`] to access the active `Rocket` instance.\n * `Request::uri()` now returns an `&Origin<'r>` instead of `&Origin<'_>`.\n * `Request::accept()`, `Request::content_type()` reflect changes to `Accept`, `Content-Type`.\n * `Json`, `MsgPack` accept `T: Deserialize`, not only `T: DeserializeOwned`.\n * Diesel SQLite connections in `rocket_sync_db_pools` use better defaults.\n * The default number of workers for synchronous database pools is now `workers * 4`.\n * Added [`Request::host()`] to retrieve the client-requested host.\n\n### Response\n\n * Added [`Template::try_custom()`] for fallible template engine customization.\n * Manually registered templates can now be rendered with `Template::render()`.\n * Added support for the `X-DNS-Prefetch-Control` header to `Shield`.\n * Added support for manually-set `expires` values for private cookies.\n * Added support for type generics and custom generic bounds to\n [`#[derive(Responder)]`](https://api.rocket.rs/v0.5/rocket/derive.Responder.html).\n * The `Server` header is only set if one isn't already set.\n * Accurate `Content-Length` headers are sent even for partially read `Body`s.\n * [`Redirect`] now accepts a `TryFrom`, allowing fragment parts.\n\n### Trait Implementations\n\n * Implemented `Clone` for `State`.\n * Implemented `Copy` and `Clone` for `fairing::Info`.\n * Implemented `Debug` for `Rocket` and `Client`.\n * Implemented `Default` for `Status` (returns `Status::Ok`).\n * Implemented `PartialEq`, `Eq`, `Hash`, `PartialOrd`, and `Ord` for `Status`.\n * Implemented `Eq`, `Hash`, and `PartialEq<&str>` for `Origin`.\n * Implemented `PartialEq>>` for `RawStr`.\n * Implemented `std::error::Error` for `Error`.\n * Implemented `Deref` and `DerefMut` for `LocalRequest` (to `Request`).\n * Implemented `DerefMut` for `Form`, `LenientForm`.\n * Implemented `From` for `Json`, `MsgPack`.\n * Implemented `TryFrom` and `TryFrom<&str>` for `Origin`.\n * Implemented `TryFrom` for each of the specific URI variants.\n * Implemented `FromRequest` for `&Config`.\n * Implemented `FromRequest` for `IpAddr`.\n * Implemented `FromParam` for `PathBuf`\n * Implemented `FromParam`, `FromData`, and `FromForm` for `&str`.\n * Implemented `FromForm` for `Json`, `MsgPack`.\n * Implemented `FromFormField` for `Cow` and `Capped>`\n * Implemented `Responder` for `tokio::fs::File`.\n * Implemented `Responder` for `(ContentType, R) where R: Responder`.\n * Implemented `Responder` for `(Status, R) where R: Responder` which overrides `R`'s status.\n * Implemented `Responder` for `std::io::Error` (behaves as `Debug`).\n * Implemented `Responder` for `Either`, equivalently to `Result`.\n * Implemented `Serialize` for `Flash`.\n * Implemented `Serialize`, `Deserialize`, `UriDisplay` and `FromUriParam` for `uuid::Uuid`\n * Implemented `Serialize`, `Deserialize` for `RawStr`.\n * Implemented `Serialize`, `Deserialize` for all URI types.\n * Implemented `Responder` for `Arc`, `Box` where `T: Responder`.\n * Implemented `Serialize` and `Deserialize` for [`Method`].\n * Implemented `Eq` for [`MediaType`] and [`ContentType`].\n * Implemented `Responder` for `Box`.\n * Implemented `FromForm` for `Arc`.\n * Implemented `Fairing` for `Arc`.\n * Implemented `Serialize` and `Deserialize` for `Status`.\n\n### Dependency Changes\n\n * `serde` was introduced (`1.0`).\n * `futures` was introduced (`0.3`).\n * `binascii` was introduced (`0.1`).\n * `ref-cast` was introduced (`1.0`).\n * `atomic` was introduced (`0.5`).\n * `parking_lot` was introduced (`0.11`).\n * `ubtye` was introduced (`0.10`).\n * `figment` was introduced (`0.10`).\n * `rand` was introduced (`0.8`).\n * `either` was introduced (`1.0`).\n * `pin-project-lite` was introduced (`0.2`).\n * `indexmap` was introduced (`2.0`).\n * `tempfile` was introduced (`3.0`).\n * `async-trait` was introduced (`0.1`).\n * `async-stream` was introduced (`0.3`).\n * `multer` was introduced (`2.0`).\n * `tokio` was introduced (`1.6.1`).\n * `tokio-util` was introduced (`0.6`).\n * `tokio-stream` was introduced (`0.1.6`).\n * `bytes` was introduced (`1.0`).\n * `normpath` was introduced (`1`).\n * `state` was updated to `0.6`.\n * `rmp-serde` was updated to `0.15`.\n * `uuid` was updated to `0.8`.\n * `tera` was updated to `1.10`.\n * `postgres` was updated to `0.19`.\n * `rusqlite` was updated to `0.25`.\n * `r2d2_sqlite` was updated to `0.18`.\n * `time` was updated to `0.3`.\n * `handlebars` was updated to `4.0`.\n * `memcache` was updated to `0.16`.\n * `rustls` was updated to `0.21`.\n * `tokio-rustls` was updated to `0.24`.\n * `syn` was updated to `2`.\n * `diesel` was updated to `2.0`.\n * `sqlx` was updated to `0.7`.\n * `notify` was updated to `6`.\n * `criterion` was updated to `0.4`.\n * `cookie` was updated to `0.18`.\n * `yansi` was updated to `1.0`.\n * `atty` was removed.\n\n## Infrastructure\n\nThe following changes were made to the project's infrastructure:\n\n * Rocket now uses the 2021 edition of Rust.\n * Added a [v0.4 to v0.5 migration guide] and [FAQ] to Rocket's website.\n * Added visible `use` statements to examples in the guide.\n * Split examples into a separate workspace for easier testing.\n * Updated documentation for all changes.\n * Fixed many typos, errors, and broken links throughout documentation and examples.\n * Improved the general robustness of macros, and the quality and frequency of error messages.\n * Benchmarks now use `criterion` and datasets extracted from real-world projects.\n * Fixed the SPDX license expressions in `Cargo.toml` files.\n * Added support to `test.sh` for a `+` flag (e.g. `+stable`) to pass to `cargo`.\n * Added support to `test.sh` for extra flags to be passed on to `cargo`.\n * UI tests are now allowed to fail by the CI to avoid false negatives.\n * The GitHub CI workflow was updated to use maintained actions.\n * The CI now frees disk space before proceeding to avoid out-of-disk errors.\n * All workspaces now use `resolver = 2`.\n\n[phase]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#phases\n[`async`/`await`]: https://rocket.rs/v0.5/guide/overview/#async-routes\n[compilation on Rust's stable]: https://rocket.rs/v0.5/guide/getting-started/#installing-rust\n[Feature-complete forms support]: https://rocket.rs/v0.5/guide/requests/#forms\n[configuration system]: https://rocket.rs/v0.5/guide/configuration/#configuration\n[graceful shutdown]: https://api.rocket.rs/v0.5/rocket/config/struct.Shutdown.html#summary\n[asynchronous testing]: https://rocket.rs/v0.5/guide/testing/#asynchronous-testing\n[UTF-8 characters]: https://rocket.rs/v0.5/guide/requests/#static-parameters\n[ignorable segments]: https://rocket.rs/v0.5/guide/requests/#ignored-segments\n[Catcher scoping]: https://rocket.rs/v0.5/guide/requests/#scoping\n[ad-hoc validation]: https://rocket.rs/v0.5/guide/requests#ad-hoc-validation\n[incoming data limits]: https://rocket.rs/v0.5/guide/requests/#streaming\n[build phases]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#phases\n[Singleton fairings]: https://api.rocket.rs/v0.5/rocket/fairing/trait.Fairing.html#singletons\n[features into core]: https://api.rocket.rs/v0.5/rocket/index.html#features\n[features of `rocket`]: https://api.rocket.rs/v0.5/rocket/index.html#features\n[Data limit declaration in SI units]: https://api.rocket.rs/v0.5/rocket/data/struct.ByteUnit.html\n[support for `serde`]: https://api.rocket.rs/v0.5/rocket/serde/index.html\n[automatic typed config extraction]: https://api.rocket.rs/v0.5/rocket/fairing/struct.AdHoc.html#method.config\n[misconfigured secrets]: https://api.rocket.rs/v0.5/rocket/config/struct.SecretKey.html\n[default ranking colors]: https://rocket.rs/v0.5/guide/requests/#default-ranking\n[`chat`]: https://github.com/rwf2/Rocket/tree/v0.5/examples/chat\n[`Form` guard]: https://api.rocket.rs/v0.5/rocket/form/struct.Form.html\n[`Strict`]: https://api.rocket.rs/v0.5/rocket/form/struct.Strict.html\n[`CookieJar`#pending]: https://api.rocket.rs/v0.5/rocket/http/struct.CookieJar.html#pending\n[`rocket::serde::json`]: https://api.rocket.rs/v0.5/rocket/serde/json/index.html\n[`rocket::serde::msgpack`]: https://api.rocket.rs/v0.5/rocket/serde/msgpack/index.html\n[`rocket::serde::uuid`]: https://api.rocket.rs/v0.5/rocket/serde/uuid/index.html\n[`rocket::shield`]: https://api.rocket.rs/v0.5/rocket/shield/index.html\n[`rocket::fs`]: https://api.rocket.rs/v0.5/rocket/fs/index.html\n[`async run()`]: https://api.rocket.rs/v0.5/rocket_sync_db_pools/index.html#handlers\n[`LocalRequest::json()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalRequest.html#method.json\n[`LocalRequest::msgpack()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalRequest.html#method.msgpack\n[`LocalResponse::json()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalResponse.html#method.json\n[`LocalResponse::msgpack()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalResponse.html#method.msgpack\n[hierarchical data limits]: https://api.rocket.rs/v0.5/rocket/data/struct.Limits.html#hierarchy\n[default form field values]: https://rocket.rs/v0.5/guide/requests/#defaults\n[`Config::ident`]: https://api.rocket.rs/rocket/struct.Config.html#structfield.ident\n[`tokio`]: https://tokio.rs/\n[Figment]: https://docs.rs/figment/0.10/figment/\n[`TempFile`]: https://api.rocket.rs/v0.5/rocket/fs/enum.TempFile.html\n[`Contextual`]: https://rocket.rs/v0.5/guide/requests/#context\n[`Capped`]: https://api.rocket.rs/v0.5/rocket/data/struct.Capped.html\n[default catchers]: https://rocket.rs/v0.5/guide/requests/#default-catchers\n[URI types]: https://api.rocket.rs/v0.5/rocket/http/uri/index.html\n[`uri!`]: https://api.rocket.rs/v0.5/rocket/macro.uri.html\n[`Reference`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Reference.html\n[`Asterisk`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Asterisk.html\n[`Redirect`]: https://api.rocket.rs/v0.5/rocket/response/struct.Redirect.html\n[`UriDisplayQuery`]: https://api.rocket.rs/v0.5/rocket/derive.UriDisplayQuery.html\n[`Shield`]: https://api.rocket.rs/v0.5/rocket/shield/struct.Shield.html\n[Sentinels]: https://api.rocket.rs/v0.5/rocket/trait.Sentinel.html\n[`local_cache!`]: https://api.rocket.rs/v0.5/rocket/request/macro.local_cache.html\n[`local_cache_once!`]: https://api.rocket.rs/v0.5/rocket/request/macro.local_cache_once.html\n[`CookieJar`]: https://api.rocket.rs/v0.5/rocket/http/struct.CookieJar.html\n[asynchronous streams]: https://rocket.rs/v0.5/guide/responses/#async-streams\n[Server-Sent Events]: https://api.rocket.rs/v0.5/rocket/response/stream/struct.EventStream.html\n[`fs::relative!`]: https://api.rocket.rs/v0.5/rocket/fs/macro.relative.html\n[notification]: https://api.rocket.rs/v0.5/rocket/struct.Shutdown.html\n[`Rocket`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html\n[`rocket::build()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.build\n[`Rocket::ignite()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.ignite\n[`Rocket::launch()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.launch\n[`Request::rocket()`]: https://api.rocket.rs/v0.5/rocket/request/struct.Request.html#method.rocket\n[Fairings]: https://rocket.rs/v0.5/guide/fairings/\n[configuration system]: https://rocket.rs/v0.5/guide/configuration/\n[`Poolable`]: https://api.rocket.rs/v0.5/rocket_sync_db_pools/trait.Poolable.html\n[`Config`]: https://api.rocket.rs/v0.5/rocket/struct.Config.html\n[`Error`]: https://api.rocket.rs/v0.5/rocket/struct.Error.html\n[`LogLevel`]: https://api.rocket.rs/v0.5/rocket/config/enum.LogLevel.html\n[`Rocket::register()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.register\n[`NamedFile::open`]: https://api.rocket.rs/v0.5/rocket/fs/struct.NamedFile.html#method.open\n[`Request::local_cache_async()`]: https://api.rocket.rs/v0.5/rocket/request/struct.Request.html#method.local_cache_async\n[`FromRequest`]: https://api.rocket.rs/v0.5/rocket/request/trait.FromRequest.html\n[`Fairing`]: https://api.rocket.rs/v0.5/rocket/fairing/trait.Fairing.html\n[`catcher::Handler`]: https://api.rocket.rs/v0.5/rocket/catcher/trait.Handler.html\n[`route::Handler`]: https://api.rocket.rs/v0.5/rocket/route/trait.Handler.html\n[`FromData`]: https://api.rocket.rs/v0.5/rocket/data/trait.FromData.html\n[`AsyncRead`]: https://docs.rs/tokio/1/tokio/io/trait.AsyncRead.html\n[`AsyncSeek`]: https://docs.rs/tokio/1/tokio/io/trait.AsyncSeek.html\n[`rocket::local::asynchronous`]: https://api.rocket.rs/v0.5/rocket/local/asynchronous/index.html\n[`rocket::local::blocking`]: https://api.rocket.rs/v0.5/rocket/local/blocking/index.html\n[`Outcome`]: https://api.rocket.rs/v0.5/rocket/outcome/enum.Outcome.html\n[`rocket::outcome::try_outcome!`]: https://api.rocket.rs/v0.5/rocket/outcome/macro.try_outcome.html\n[`Result` implements `Responder`]: https://api.rocket.rs/v0.5/rocket/response/trait.Responder.html#provided-implementations\n[`Debug`]: https://api.rocket.rs/v0.5/rocket/response/struct.Debug.html\n[`std::convert::Infallible`]: https://doc.rust-lang.org/stable/std/convert/enum.Infallible.html\n[`ErrorKind::Collisions`]: https://api.rocket.rs/v0.5/rocket/error/enum.ErrorKind.html#variant.Collisions\n[`rocket::http::uri::fmt`]: https://api.rocket.rs/v0.5/rocket/http/uri/fmt/index.html\n[`Data::open()`]: https://api.rocket.rs/v0.5/rocket/data/struct.Data.html#method.open\n[`DataStream`]: https://api.rocket.rs/v0.5/rocket/data/struct.DataStream.html\n[`rocket::form`]: https://api.rocket.rs/v0.5/rocket/form/index.html\n[`FromFormField`]: https://api.rocket.rs/v0.5/rocket/form/trait.FromFormField.html\n[`FromForm`]: https://api.rocket.rs/v0.5/rocket/form/trait.FromForm.html\n[`FlashMessage`]: https://api.rocket.rs/v0.5/rocket/request/type.FlashMessage.html\n[`Flash`]: https://api.rocket.rs/v0.5/rocket/response/struct.Flash.html\n[`rocket::State`]: https://api.rocket.rs/v0.5/rocket/struct.State.html\n[`Segments` and `Segments`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Segments.html\n[`Route::map_base()`]: https://api.rocket.rs/v0.5/rocket/route/struct.Route.html#method.map_base\n[`uuid` support]: https://api.rocket.rs/v0.5/rocket/serde/uuid/index.html\n[`json`]: https://api.rocket.rs/v0.5/rocket/serde/json/index.html\n[`msgpack`]: https://api.rocket.rs/v0.5/rocket/serde/msgpack/index.html\n[`rocket::serde::json::json!`]: https://api.rocket.rs/v0.5/rocket/serde/json/macro.json.html\n[`rocket::shield::Shield`]: https://api.rocket.rs/v0.5/rocket/shield/struct.Shield.html\n[`rocket::fs::FileServer`]: https://api.rocket.rs/v0.5/rocket/fs/struct.FileServer.html\n[`rocket_dyn_templates`]: https://api.rocket.rs/v0.5/rocket_dyn_templates/index.html\n[`rocket_sync_db_pools`]: https://api.rocket.rs/v0.5/rocket_sync_db_pools/index.html\n[multitasking]: https://rocket.rs/v0.5/guide/overview/#multitasking\n[`Created`]: https://api.rocket.rs/v0.5/rocket/response/status/struct.Created.html\n[`Created::tagged_body`]: https://api.rocket.rs/v0.5/rocket/response/status/struct.Created.html#method.tagged_body\n[raw identifiers]: https://doc.rust-lang.org/1.51.0/book/appendix-01-keywords.html#raw-identifiers\n[`Rocket::config()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.config\n[`Rocket::figment()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.figment\n[`Rocket::state()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.state\n[`Rocket::catchers()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.catchers\n[`LocalRequest::inner_mut()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalRequest.html#method.inner_mut\n[`RawStrBuf`]: https://api.rocket.rs/v0.5/rocket/http/struct.RawStrBuf.html\n[`RawStr`]: https://api.rocket.rs/v0.5/rocket/http/struct.RawStr.html\n[`RawStr::percent_encode()`]: https://api.rocket.rs/v0.5/rocket/http/struct.RawStr.html#method.percent_encode\n[`RawStr::percent_encode_bytes()`]: https://api.rocket.rs/v0.5/rocket/http/struct.RawStr.html#method.percent_encode_bytes\n[`RawStr::strip()`]: https://api.rocket.rs/v0.5/rocket/http/struct.RawStr.html#method.strip_prefix\n[`rocket::catcher`]: https://api.rocket.rs/v0.5/rocket/catcher/index.html\n[`rocket::route`]: https://api.rocket.rs/v0.5/rocket/route/index.html\n[`Segments::prefix_of()`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Segments.html#method.prefix_of\n[`Template::try_custom()`]: https://api.rocket.rs/v0.5/rocket_dyn_templates/struct.Template.html#method.try_custom\n[`Template::custom`]: https://api.rocket.rs/v0.5/rocket_dyn_templates/struct.Template.html#method.custom\n[`FileServer::new()`]: https://api.rocket.rs/v0.5/rocket/fs/struct.FileServer.html#method.new\n[`content`]: https://api.rocket.rs/v0.5/rocket/response/content/index.html\n[`rocket_db_pools`]: https://api.rocket.rs/v0.5/rocket_db_pools/index.html\n[mutual TLS]: https://rocket.rs/v0.5/guide/configuration/#mutual-tls\n[`Certificate`]: https://api.rocket.rs/v0.5/rocket/mtls/struct.Certificate.html\n[`MediaType::with_params()`]: https://api.rocket.rs/v0.5/rocket/http/struct.MediaType.html#method.with_params\n[`ContentType::with_params()`]: https://api.rocket.rs/v0.5/rocket/http/struct.ContentType.html#method.with_params\n[`Host`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Host.html\n[`&Host`]: https://api.rocket.rs/v0.5/rocket/http/uri/struct.Host.html\n[`Request::host()`]: https://api.rocket.rs/v0.5/rocket/request/struct.Request.html#method.host\n[`context!`]: https://api.rocket.rs/v0.5/rocket_dyn_templates/macro.context.html\n[`MediaType`]: https://api.rocket.rs/v0.5/rocket/http/struct.MediaType.html\n[`ContentType`]: https://api.rocket.rs/v0.5/rocket/http/struct.ContentType.html\n[`Method`]: https://api.rocket.rs/v0.5/rocket/http/enum.Method.html\n[`(ContentType, T)`]: https://api.rocket.rs/v0.5/rocket/response/content/index.html#usage\n[v0.4 to v0.5 migration guide]: https://rocket.rs/v0.5/guide/upgrading/\n[contrib deprecation upgrade guide]: https://rocket.rs/v0.5/guide/upgrading/#contrib-deprecation\n[FAQ]: https://rocket.rs/v0.5/guide/faq/\n[`Rocket::launch()`]: https://api.rocket.rs/v0.5/rocket/struct.Rocket.html#method.launch\n[`ErrorKind::Shutdown`]: https://api.rocket.rs/v0.5/rocket/error/enum.ErrorKind.html#variant.Shutdown\n[shutdown fairings]: https://api.rocket.rs/v0.5/rocket/fairing/trait.Fairing.html#shutdown\n[`Client::terminate()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.Client.html#method.terminate\n[`rocket::execute()`]: https://api.rocket.rs/v0.5/rocket/fn.execute.html\n[`CookieJar::get_pending()`]: https://api.rocket.rs/v0.5/rocket/http/struct.CookieJar.html#method.get_pending\n[`Metadata::render()`]: https://api.rocket.rs/v0.5/rocket_dyn_templates/struct.Metadata.html#method.render\n[`pool()`]: https://api.rocket.rs/v0.5/rocket_sync_db_pools/example/struct.ExampleDb.html#method.pool\n[`Request::client_ip()`]: https://api.rocket.rs/v0.5/rocket/request/struct.Request.html#method.client_ip\n[`max_blocking`]: https://api.rocket.rs/v0.5/rocket/struct.Config.html#structfield.max_blocking\n[`ip_header`]: https://api.rocket.rs/v0.5/rocket/struct.Config.html#structfield.ip_header\n[`LocalRequest::identity()`]: https://api.rocket.rs/v0.5/rocket/local/blocking/struct.LocalRequest.html#method.identity\n[`TempFile::open()`]: https://api.rocket.rs/v0.5/rocket/fs/enum.TempFile.html#method.open\n[`Error::pretty_print()`]: https://api.rocket.rs/v0.5/rocket/struct.Error.html#method.pretty_print\n[Request connection upgrade APIs]: https://api.rocket.rs/v0.5/rocket/struct.Response.html#upgrading\n[`rocket_ws`]: https://api.rocket.rs/v0.5/rocket_ws/\n[registering]: https://api.rocket.rs/v0.5/rocket/response/struct.Response.html#method.add_upgrade\n[`IoHandler`]: https://api.rocket.rs/v0.5/rocket/data/trait.IoHandler.html\n[`response::status`]: https://api.rocket.rs/v0.5/rocket/response/status/index.html\n[Custom form errors]: https://api.rocket.rs/v0.5/rocket/form/error/enum.ErrorKind.html#variant.Custom\n[`request::Outcome`]: https://api.rocket.rs/v0.5/rocket/request/type.Outcome.html#variant.Forward\n[Route `Forward` outcomes]: https://api.rocket.rs/v0.5/rocket/request/type.Outcome.html#variant.Forward\n[`Outcome::Error`]: https://api.rocket.rs/v0.5/rocket/outcome/enum.Outcome.html#variant.Error\n[`IntoOutcome`]: https://api.rocket.rs/v0.5/rocket/outcome/trait.IntoOutcome.html\n[`MediaType::JavaScript`]: https://api.rocket.rs/v0.5/rocket/http/struct.MediaType.html#associatedconstant.JavaScript\n[`TempFile::open()`]: https://api.rocket.rs/v0.5/rocket/fs/enum.TempFile.html#method.open\n[`Error::pretty_print()`]: https://api.rocket.rs/v0.5/rocket/struct.Error.html#method.pretty_print\n[`RouteUri`]: https://api.rocket.rs/v0.5/rocket/route/struct.RouteUri.html\n\n# Version 0.4.10 (May 21, 2021)\n\n## Core\n\n * [[`3276b8`]] Removed `unsafe` in `Origin::parse_owned()`, fixing a soundness\n issue.\n\n[`3276b8`]: https://github.com/rwf2/Rocket/commit/3276b8\n\n# Version 0.4.9 (May 19, 2021)\n\n## Core\n\n * [[`#1645`], [`f2a56f`]] Fixed `Try` `impl FromResidual for Outcome`.\n\n[`#1645`]: https://github.com/rwf2/Rocket/issues/1645\n[`f2a56f`]: https://github.com/rwf2/Rocket/commit/f2a56f\n\n# Version 0.4.8 (May 18, 2021)\n\n## Core\n\n * [[`#1548`], [`93e88b0`]] Fixed an issue that prevented compilation under\n Windows Subsystem for Linux v1.\n * Updated `Outcome` `Try` implementation to v2 in latest nightly.\n * Minimum required `rustc` is `1.54.0-nightly (2021-05-18)`.\n\n## Internal\n\n * Updated `base64` dependency to `0.13`.\n\n[`#1548`]: https://github.com/rwf2/Rocket/issues/1548\n[`93e88b0`]: https://github.com/rwf2/Rocket/commit/93e88b0\n\n# Version 0.4.7 (Feb 09, 2021)\n\n## Core\n\n * [[#1534], [`2059a6`]] Fixed a low-severity, minimal impact soundness issue\n in `uri::Formatter`.\n\n[#1534]: https://github.com/rwf2/Rocket/issues/1534\n[`2059a6`]: https://github.com/rwf2/Rocket/commit/2059a6\n\n# Version 0.4.6 (Nov 09, 2020)\n\n## Core\n\n * [[`86bd7c`]] Added default and configurable read/write timeouts:\n `read_timeout` and `write_timeout`.\n * [[`c24a96`]] Added the `sse` feature, which [enables flushing] by returning\n `io::ErrorKind::WouldBlock`.\n\n## Docs\n\n * Fixed broken doc links in `contrib`.\n * Fixed database library versions in `contrib` docs.\n\n## Internal\n\n * Updated source code for Rust 2018.\n * UI tests now use `trybuild` instead of `compiletest-rs`.\n\n[`86bd7c`]: https://github.com/rwf2/Rocket/commit/86bd7c\n[`c24a96`]: https://github.com/rwf2/Rocket/commit/c24a96\n[enables flushing]: https://api.rocket.rs/v0.4/rocket/response/struct.Stream.html#buffering-and-blocking\n\n# Version 0.4.5 (May 30, 2020)\n\n## Core\n\n * [[#1312], [`89150f`]] Fixed a low-severity, minimal impact soundness issue in\n `LocalRequest::clone()`.\n * [[#1263], [`376f74`]] Fixed a cookie serialization issue that led to\n incorrect cookie deserialization in certain cases.\n * Removed dependency on `ring` for private cookies and thus Rocket, by\n default.\n * Added [`Origin::map_path()`] for manipulating `Origin` paths.\n * Added [`handler::Outcome::from_or_forward()`].\n * Added [`Options::NormalizeDirs`] option to `StaticFiles`.\n * Improved accessibility of default error HTML.\n\n## Docs\n\n * Fixed various typos.\n\n[#1312]: https://github.com/rwf2/Rocket/issues/1312\n[`89150f`]: https://github.com/rwf2/Rocket/commit/89150f\n[#1263]: https://github.com/rwf2/Rocket/issues/1263\n[`376f74`]: https://github.com/rwf2/Rocket/commit/376f74\n[`Origin::map_path()`]: https://api.rocket.rs/v0.4/rocket/http/uri/struct.Origin.html#method.map_path\n[`handler::Outcome::from_or_forward()`]: https://api.rocket.rs/v0.4/rocket/handler/type.Outcome.html#method.from_or_forward\n[`Options::NormalizeDirs`]: https://api.rocket.rs/v0.4/rocket_contrib/serve/struct.Options.html#associatedconstant.NormalizeDirs\n\n# Version 0.4.4 (Mar 09, 2020)\n\n## Core\n\n * Removed use of unsupported `cfg(debug_assertions)` in `Cargo.toml`, allowing\n for builds on latest nightlies.\n\n## Docs\n\n * Fixed various broken links.\n\n# Version 0.4.3 (Feb 29, 2020)\n\n## Core\n\n * Added a new [`Debug`] `500` `Responder` that `Debug`-prints its contents on\n response.\n * Specialization on `Result` was deprecated. [`Debug`] can be used in place of\n non-`Responder` errors.\n * Fixed an issue that resulted in cookies not being set on error responses.\n * Various `Debug` implementations on Rocket types now respect formatting\n options.\n * Added `Responder`s for various HTTP status codes: [`NoContent`],\n [`Unauthorized`], [`Forbidden`], and [`Conflict`].\n * `FromParam` is implemented for `NonZero` core types.\n\n## Codegen\n\n * Docs for Rocket-generated macros are now hidden.\n * Generated code now works even when prelude imports like `Some`, `Ok`, and\n `Err` are shadowed.\n * Error messages referring to responder types in routes now point to the type\n correctly.\n\n## Docs\n\n * All code examples in the guide are now tested and guaranteed to compile.\n * All macros are documented in the `core` crate; `rocket_codegen` makes no\n appearances.\n\n## Infrastructure\n\n * CI was moved from Travis to Azure Pipelines; Windows support is tested.\n * Rocket's chat moved to [Matrix] and [Freenode].\n\n[`Debug`]: https://api.rocket.rs/v0.4/rocket/response/struct.Debug.html\n[`NoContent`]: https://api.rocket.rs/v0.4/rocket/response/status/struct.NoContent.html\n[`Unauthorized`]: https://api.rocket.rs/v0.4/rocket/response/status/struct.Unauthorized.html\n[`Forbidden`]: https://api.rocket.rs/v0.4/rocket/response/status/struct.Forbidden.html\n[`Conflict`]: https://api.rocket.rs/v0.4/rocket/response/status/struct.Conflict.html\n[Matrix]: https://chat.mozilla.org/#/room/#rocket:mozilla.org\n[Freenode]: https://kiwiirc.com/client/chat.freenode.net/#rocket\n\n# Version 0.4.2 (Jun 28, 2019)\n\n## Core\n\n * Replaced use of `FnBox` with `Box`.\n * Removed the stable feature gates `try_from` and `transpose_result`.\n * Derive macros are reexported alongside their respective traits.\n * Minimum required `rustc` is `1.35.0-nightly (2019-04-05)`.\n\n## Codegen\n\n * `JsonValue` now implements `FromIterator`.\n * `non_snake_case` errors are silenced in generated code.\n * Minimum required `rustc` is `1.33.0-nightly (2019-01-03)`.\n\n## Contrib\n\n * Allow setting custom ranks on `StaticFiles` via [`StaticFiles::rank()`].\n * `MsgPack` correctly sets a MessagePack Content-Type on responses.\n\n## Docs\n\n * Fixed typos across rustdocs and guide.\n * Documented library versions in contrib database documentation.\n\n## Infrastructure\n\n * Updated internal dependencies to their latest versions.\n\n[`StaticFiles::rank()`]: https://api.rocket.rs/v0.4/rocket_contrib/serve/struct.StaticFiles.html#method.rank\n\n# Version 0.4.1 (May 11, 2019)\n\n## Core\n\n * Rocket's default `Server` HTTP header no longer overrides a user-set header.\n * Fixed encoding and decoding of certain URI characters.\n\n## Codegen\n\n * Compiler diagnostic information is more reliably produced.\n\n## Contrib\n\n * Database pool types now implement `DerefMut`.\n * Added support for memcache connection pools.\n * Stopped depending on default features from core.\n\n## Docs\n\n * Fixed many typos across the rustdocs and guide.\n * Added guide documentation on mounting more than one route at once.\n\n## Infrastructure\n\n * Testing no longer requires \"bootstrapping\".\n * Removed deprecated `isatty` dependency in favor of `atty`.\n\n# Version 0.4.0 (Dec 06, 2018)\n\n## New Features\n\nThis release includes the following new features:\n\n * Introduced [Typed URIs].\n * Introduced [ORM agnostic database support].\n * Introduced [Request-Local State].\n * Introduced mountable static-file serving via [`StaticFiles`].\n * Introduced automatic [live template reloading].\n * Introduced custom stateful handlers via [`Handler`].\n * Introduced [transforming] data guards via [`FromData::transform()`].\n * Introduced revamped [query string handling].\n * Introduced the [`SpaceHelmet`] security and privacy headers fairing.\n * Private cookies are gated behind a `private-cookies` default feature.\n * Added [derive for `FromFormValue`].\n * Added [derive for `Responder`].\n * Added [`Template::custom()`] for customizing templating engines including\n registering filters and helpers.\n * Cookies are automatically tracked and propagated by [`Client`].\n * Private cookies can be added to local requests with\n [`LocalRequest::private_cookie()`].\n * Release builds default to the `production` environment.\n * Keep-alive can be configured via the `keep_alive` configuration parameter.\n * Allow CLI colors and emoji to be disabled with `ROCKET_CLI_COLORS=off`.\n * Route `format` accepts [shorthands] such as `json` and `html`.\n * Implemented [`Responder` for `Status`].\n * Added [`Response::cookies()`] for retrieving response cookies.\n * All logging is disabled when `log` is set to `off`.\n * Added [`Metadata`] guard for retrieving templating information.\n * The [`Uri`] type parses URIs according to RFC 7230 into one of [`Origin`],\n [`Absolute`], or [`Authority`].\n * Added [`Outcome::and_then()`], [`Outcome::failure_then()`], and\n [`Outcome::forward_then()`].\n * Implemented `Responder` for `&[u8]`.\n * Any `T: Into>` can be [`mount()`]ed.\n * [Default rankings] range from -6 to -1, differentiating on static query\n strings.\n * Added [`Request::get_query_value()`] for retrieving a query value by key.\n * Applications can launch without a working directory.\n * Added [`State::from()`] for constructing `State` values.\n\n[`SpaceHelmet`]: https://api.rocket.rs/v0.4/rocket_contrib/helmet/index.html\n[`State::from()`]: https://api.rocket.rs/v0.4/rocket/struct.State.html#method.from\n[Typed URIs]: https://rocket.rs/v0.4/guide/responses/#typed-uris\n[ORM agnostic database support]: https://rocket.rs/v0.4/guide/state/#databases\n[`Template::custom()`]: https://api.rocket.rs/v0.4/rocket_contrib/templates/struct.Template.html#method.custom\n[`LocalRequest::private_cookie()`]: https://api.rocket.rs/v0.4/rocket/local/struct.LocalRequest.html#method.private_cookie\n[`LocalRequest`]: https://api.rocket.rs/v0.4/rocket/local/struct.LocalRequest.html\n[shorthands]: https://api.rocket.rs/v0.4/rocket/http/struct.ContentType.html#method.parse_flexible\n[derive for `FromFormValue`]: https://api.rocket.rs/v0.4/rocket_codegen/derive.FromFormValue.html\n[derive for `Responder`]: https://api.rocket.rs/v0.4/rocket_codegen/derive.Responder.html\n[`Response::cookies()`]: https://api.rocket.rs/v0.4/rocket/struct.Response.html#method.cookies\n[`Client`]: https://api.rocket.rs/v0.4/rocket/local/struct.Client.html\n[Request-Local State]: https://rocket.rs/v0.4/guide/state/#request-local-state\n[`Metadata`]: https://api.rocket.rs/v0.4/rocket_contrib/templates/struct.Metadata.html\n[`Uri`]: https://api.rocket.rs/v0.4/rocket/http/uri/enum.Uri.html\n[`Origin`]: https://api.rocket.rs/v0.4/rocket/http/uri/struct.Origin.html\n[`Absolute`]: https://api.rocket.rs/v0.4/rocket/http/uri/struct.Absolute.html\n[`Authority`]: https://api.rocket.rs/v0.4/rocket/http/uri/struct.Authority.html\n[`Outcome::and_then()`]: https://api.rocket.rs/v0.4/rocket/enum.Outcome.html#method.and_then\n[`Outcome::forward_then()`]: https://api.rocket.rs/v0.4/rocket/enum.Outcome.html#method.forward_then\n[`Outcome::failure_then()`]: https://api.rocket.rs/v0.4/rocket/enum.Outcome.html#method.failure_then\n[`StaticFiles`]: https://api.rocket.rs/v0.4/rocket_contrib/serve/struct.StaticFiles.html\n[live template reloading]: https://rocket.rs/v0.4/guide/responses/#live-reloading\n[`Handler`]: https://api.rocket.rs/v0.4/rocket/trait.Handler.html\n[`mount()`]: https://api.rocket.rs/v0.4/rocket/struct.Rocket.html#method.mount\n[`FromData::transform()`]: https://api.rocket.rs/v0.4/rocket/data/trait.FromData.html#tymethod.transform\n[transforming]: https://api.rocket.rs/v0.4/rocket/data/trait.FromData.html#transforming\n[query string handling]: https://rocket.rs/v0.4/guide/requests/#query-strings\n[Default rankings]: https://rocket.rs/v0.4/guide/requests/#default-ranking\n[`Request::get_query_value()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.get_query_value\n[`Responder` for `Status`]: https://rocket.rs/v0.4/guide/responses/#status\n\n## Codegen Rewrite\n\nThe [`rocket_codegen`] crate has been entirely rewritten using to-be-stable\nprocedural macro APIs. We expect nightly breakages to drop dramatically, likely\nto zero, as a result. The new prelude import for Rocket applications is:\n\n```diff\n- #![feature(plugin)]\n- #![plugin(rocket_codegen)]\n+ #![feature(proc_macro_hygiene, decl_macro)]\n\n- extern crate rocket;\n+ #[macro_use] extern crate rocket;\n```\n\nThe [`rocket_codegen`] crate should **_not_** be a direct dependency. Remove it\nfrom your `Cargo.toml`:\n\n```diff\n[dependencies]\n- rocket = \"0.3\"\n+ rocket = \"0.4\"\n- rocket_codegen = \"0.3\"\n```\n\n[`rocket_codegen`]: https://api.rocket.rs/v0.4/rocket_codegen/index.html\n\n## Breaking Changes\n\nThis release includes many breaking changes. These changes are listed below\nalong with a short note about how to handle the breaking change in existing\napplications when applicable.\n\n * **Route and catcher attributes respect function privacy.**\n\n To mount a route or register a catcher outside of the module it is declared,\n ensure that the handler function is marked `pub` or `crate`.\n\n * **Query handling syntax has been completely revamped.**\n\n A query parameter of `` is now ``. Consider whether your\n application benefits from the revamped [query string handling].\n\n * **The `#[error]` attribute and `errors!` macro were removed.**\n\n Use `#[catch]` and `catchers!` instead.\n\n * **`Rocket::catch()` was renamed to [`Rocket::register()`].**\n\n Change calls of the form `.catch(errors![..])` to\n `.register(catchers![..])`.\n\n * **The `#[catch]` attribute only accepts functions with 0 or 1 argument.**\n\n Ensure the argument to the catcher, if any, is of type `&Request`.\n\n * **[`json!`] returns a [`JsonValue`], no longer needs wrapping.**\n\n Change instances of `Json(json!(..))` to `json!` and change the\n corresponding type to `JsonValue`.\n\n * **All environments default to port 8000.**\n\n Manually configure a port of `80` for the `stage` and `production`\n environments for the previous behavior.\n\n * **Release builds default to the production environment.**\n\n Manually set the environment to `debug` with `ROCKET_ENV=debug` for the\n previous behavior.\n\n * **[`Form`] and [`LenientForm`] lost a lifetime parameter, `get()` method.**\n\n Change a type of `Form<'a, T<'a>>` to `Form` or `Form>`. `Form`\n and `LenientForm` now implement `Deref`, allowing for calls\n to `.get()` to be removed.\n\n * **[`ring`] was updated to 0.13.**\n\n Ensure all transitive dependencies to `ring` refer to version `0.13`.\n\n * **`Uri` was largely replaced by [`Origin`].**\n\n In general, replace the type `Uri` with `Origin`. The `base` and `uri`\n fields of [`Route`] are now of type [`Origin`]. The `&Uri` guard is now\n `&Origin`. [`Request::uri()`] now returns an [`Origin`].\n\n * **All items in [`rocket_contrib`] are namespaced behind modules.**\n\n * `Json` is now `json::Json`\n * `MsgPack` is now `msgpack::MsgPack`\n * `MsgPackError` is now `msgpack::Error`\n * `Template` is now `templates::Template`\n * `UUID` is now `uuid::Uuid`\n * `Value` is replaced by `json::JsonValue`\n\n * **TLS certificates require the `subjectAltName` extension.**\n\n Ensure that your TLS certificates contain the `subjectAltName` extension\n with a value set to your domain.\n\n * **Route paths, mount points, and [`LocalRequest`] URIs are strictly\n checked.**\n\n Ensure your mount points are absolute paths with no parameters, ensure your\n route paths are absolute paths with proper parameter syntax, and ensure that\n paths passed to `LocalRequest` are valid.\n\n * **[`Template::show()`] takes an `&Rocket`, doesn't accept a `root`.**\n\n Use [`client.rocket()`] to get a reference to an instance of `Rocket` when\n testing. Use [`Template::render()`] in routes.\n\n * **[`Request::remote()`] returns the _actual_ remote IP, doesn't rewrite.**\n\n Use [`Request::real_ip()`] or [`Request::client_ip()`] to retrieve the IP\n address from the \"X-Real-IP\" header if it is present.\n\n * **[`Bind`] variant was added to [`LaunchErrorKind`].**\n\n Ensure matches on `LaunchErrorKind` include or ignore the `Bind` variant.\n\n * **Cookies are automatically tracked and propagated by [`Client`].**\n\n For the previous behavior, construct a `Client` with\n [`Client::untracked()`].\n\n * **`UUID` was renamed to [`Uuid`].**\n\n Use `Uuid` instead of `UUID`.\n\n * **`LocalRequest::cloned_dispatch()` was removed.**\n\n Chain calls to `.clone().dispatch()` for the previous behavior.\n\n * **[`Redirect`] constructors take a generic type of `T:\n TryInto>`.**\n\n A call to a `Redirect` constructor with a non-`'static` `&str` of the form\n `Redirect::to(string)` should become `Redirect::to(string.to_string())`,\n heap-allocating the string before being passed to the constructor.\n\n * **The [`FromData`] impl for [`Form`] and [`LenientForm`] now return an error\n of type [`FormDataError`].**\n\n On non-I/O errors, the form string is stored in the variant as an `&'f str`.\n\n * **[`Missing`] variant was added to [`ConfigError`].**\n\n Ensure matches on `ConfigError` include or ignore the `Missing` variant.\n\n * **The [`FromData`] impl for [`Json`] now returns an error of type\n [`JsonError`].**\n\n The previous `SerdeError` is now the `.1` member of the `JsonError` `enum`.\n Match and destruct the variant for the previous behavior.\n\n * **[`FromData`] is now emulated by [`FromDataSimple`].**\n\n Change _implementations_, not uses, of `FromData` to `FromDataSimple`.\n Consider whether your implementation could benefit from [transformations].\n\n * **[`FormItems`] iterates over values of type [`FormItem`].**\n\n Map using `.map(|item| item.key_value())` for the previous behavior.\n\n * **[`LaunchErrorKind::Collision`] contains a vector of the colliding routes.**\n\n Destruct using `LaunchErrorKind::Collision(..)` to ignore the vector.\n\n * **[`Request::get_param()`] and [`Request::get_segments()`] are indexed by\n _segment_, not dynamic parameter.**\n\n Modify the `n` argument in calls to these functions appropriately.\n\n * **Method-based route attributes no longer accept a keyed `path` parameter.**\n\n Change an attribute of the form `#[get(path = \"..\")]` to `#[get(\"..\")]`.\n\n * **[`Json`] and [`MsgPack`] data guards no longer reject requests with an\n unexpected Content-Type**\n\n To approximate the previous behavior, add a `format = \"json\"` route\n parameter when using `Json` or `format = \"msgpack\"` when using `MsgPack`.\n\n * **Implemented [`Responder` for `Status`]. Removed `Failure`,\n `status::NoContent`, and `status::Reset` responders.**\n\n Replace uses of `Failure(status)` with `status` directly. Replace\n `status::NoContent` with `Status::NoContent`. Replace `status::Reset` with\n `Status::ResetContent`.\n\n * **[`Config::root()`] returns an `Option<&Path>` instead of an `&Path`.**\n\n For the previous behavior, use `config.root().unwrap()`.\n\n * **[`Status::new()`] is no longer `const`.**\n\n Construct a `Status` directly.\n\n * **[`Config`] constructors return a `Config` instead of a `Result`.**\n\n * **`ConfigError::BadCWD`, `Config.config_path` were removed.**\n\n * **[`Json`] no longer has a default value for its type parameter.**\n\n * **Using `data` on a non-payload method route is a warning instead of error.**\n\n * **The `raw_form_string` method of [`Form`] and [`LenientForm`] was\n removed.**\n\n * **Various impossible `Error` associated types are now set to `!`.**\n\n * **All [`AdHoc`] constructors require a name as the first parameter.**\n\n * **The top-level `Error` type was removed.**\n\n[`LaunchErrorKind::Collision`]: https://api.rocket.rs/v0.4/rocket/error/enum.LaunchErrorKind.html#variant.Collision\n[`json!`]: https://api.rocket.rs/v0.4/rocket_contrib/macro.json.html\n[`JsonValue`]: https://api.rocket.rs/v0.4/rocket_contrib/json/struct.JsonValue.html\n[`Json`]: https://api.rocket.rs/v0.4/rocket_contrib/json/struct.Json.html\n[`ring`]: https://crates.io/crates/ring\n[`Template::show()`]: https://api.rocket.rs/v0.4/rocket_contrib/templates/struct.Template.html#method.show\n[`Template::render()`]: https://api.rocket.rs/v0.4/rocket_contrib/templates/struct.Template.html#method.render\n[`client.rocket()`]: https://api.rocket.rs/v0.4/rocket/local/struct.Client.html#method.rocket\n[`Request::remote()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.remote\n[`Request::real_ip()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.real_ip\n[`Request::client_ip()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.client_ip\n[`Bind`]: https://api.rocket.rs/v0.4/rocket/error/enum.LaunchErrorKind.html#variant.Bind\n[`LaunchErrorKind`]: https://api.rocket.rs/v0.4/rocket/error/enum.LaunchErrorKind.html\n[`Client::untracked()`]: https://api.rocket.rs/v0.4/rocket/local/struct.Client.html#method.untracked\n[`Uuid`]: https://api.rocket.rs/v0.4/rocket_contrib/uuid/struct.Uuid.html\n[`Route`]: https://api.rocket.rs/v0.4/rocket/struct.Route.html\n[`Redirect`]: https://api.rocket.rs/v0.4/rocket/response/struct.Redirect.html\n[`Request::uri()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.uri\n[`FormDataError`]: https://api.rocket.rs/v0.4/rocket/request/enum.FormDataError.html\n[`FromData`]: https://api.rocket.rs/v0.4/rocket/data/trait.FromData.html\n[`Form`]: https://api.rocket.rs/v0.4/rocket/request/struct.Form.html\n[`LenientForm`]: https://api.rocket.rs/v0.4/rocket/request/struct.LenientForm.html\n[`AdHoc`]: https://api.rocket.rs/v0.4/rocket/fairing/struct.AdHoc.html\n[`Missing`]: https://api.rocket.rs/v0.4/rocket/config/enum.ConfigError.html#variant.Missing\n[`ConfigError`]: https://api.rocket.rs/v0.4/rocket/config/enum.ConfigError.html\n[`Rocket::register()`]: https://api.rocket.rs/v0.4/rocket/struct.Rocket.html#method.register\n[`JsonError`]: https://api.rocket.rs/v0.4/rocket_contrib/json/enum.JsonError.html\n[transformations]: https://api.rocket.rs/v0.4/rocket/data/trait.FromData.html#transforming\n[`FromDataSimple`]: https://api.rocket.rs/v0.4/rocket/data/trait.FromDataSimple.html\n[`Request::get_param()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.get_param\n[`Request::get_segments()`]: https://api.rocket.rs/v0.4/rocket/struct.Request.html#method.get_segments\n[`FormItem`]: https://api.rocket.rs/v0.4/rocket/request/struct.FormItem.html\n[`rocket_contrib`]: https://api.rocket.rs/v0.4/rocket_contrib/index.html\n[`MsgPack`]: https://api.rocket.rs/v0.4/rocket_contrib/msgpack/struct.MsgPack.html\n[`Status::new()`]: https://api.rocket.rs/v0.4/rocket/http/struct.Status.html#method.new\n[`Config`]: https://api.rocket.rs/v0.4/rocket/struct.Config.html\n[`Config::root()`]: https://api.rocket.rs/v0.4/rocket/struct.Config.html#method.root\n\n## General Improvements\n\nIn addition to new features, Rocket saw the following improvements:\n\n * Log messages now refer to routes by name.\n * Collision errors on launch name the colliding routes.\n * Launch fairing failures refer to the failing fairing by name.\n * The default `403` catcher now references authorization, not authentication.\n * Private cookies are set to `HttpOnly` and are given an expiration date of 1\n week by default.\n * A [Tera templates example] was added.\n * All macros, derives, and attributes are individually documented in\n [`rocket_codegen`].\n * Invalid client requests receive a response of `400` instead of `500`.\n * Response bodies are reliably stripped on `HEAD` requests.\n * Added a default catcher for `504: Gateway Timeout`.\n * Configuration information is logged in all environments.\n * Use of `unsafe` was reduced from 9 to 2 in core library.\n * [`FormItems`] now parses empty keys and values as well as keys without\n values.\n * Added [`Config::active()`] as a shorthand for\n `Config::new(Environment::active()?)`.\n * Address/port binding errors at launch are detected and explicitly emitted.\n * [`Flash`] cookies are cleared only after they are inspected.\n * `Sync` bound on [`AdHoc::on_attach()`], [`AdHoc::on_launch()`] was removed.\n * [`AdHoc::on_attach()`], [`AdHoc::on_launch()`] accept an `FnOnce`.\n * Added [`Config::root_relative()`] for retrieving paths relative to the\n configuration file.\n * Added [`Config::tls_enabled()`] for determining whether TLS is actively\n enabled.\n * ASCII color codes are not emitted on versions of Windows that do not support\n them.\n * Added FLAC (`audio/flac`), Icon (`image/x-icon`), WEBA (`audio/webm`), TIFF\n (`image/tiff`), AAC (`audio/aac`), Calendar (`text/calendar`), MPEG\n (`video/mpeg`), TAR (`application/x-tar`), GZIP (`application/gzip`), MOV\n (`video/quicktime`), MP4 (`video/mp4`), ZIP (`application/zip`) as known\n media types.\n * Added `.weba` (`WEBA`), `.ogv` (`OGG`), `.mp4` (`MP4`), `.mpeg4` (`MP4`),\n `.aac` (`AAC`), `.ics` (`Calendar`), `.bin` (`Binary`), `.mpg` (`MPEG`),\n `.mpeg` (`MPEG`), `.tar` (`TAR`), `.gz` (`GZIP`), `.tif` (`TIFF`), `.tiff`\n (`TIFF`), `.mov` (`MOV`) as known extensions.\n * Interaction between route attributes and declarative macros has been\n improved.\n * Generated code now logs through logging infrastructures as opposed to using\n `println!`.\n * Routing has been optimized by caching routing metadata.\n * [`Form`] and [`LenientForm`] can be publicly constructed.\n * Console coloring uses default terminal colors instead of white.\n * Console coloring is consistent across all messages.\n * `i128` and `u128` now implement [`FromParam`], [`FromFormValue`].\n * The `base64` dependency was updated to `0.10`.\n * The `log` dependency was updated to `0.4`.\n * The `handlebars` dependency was updated to `1.0`.\n * The `tera` dependency was updated to `0.11`.\n * The `uuid` dependency was updated to `0.7`.\n * The `rustls` dependency was updated to `0.14`.\n * The `cookie` dependency was updated to `0.11`.\n\n[Tera templates example]: https://github.com/rwf2/Rocket/tree/v0.4/examples/tera_templates\n[`FormItems`]: https://api.rocket.rs/v0.4/rocket/request/enum.FormItems.html\n[`Config::active()`]: https://api.rocket.rs/v0.4/rocket/config/struct.Config.html#method.active\n[`Flash`]: https://api.rocket.rs/v0.4/rocket/response/struct.Flash.html\n[`AdHoc::on_attach()`]: https://api.rocket.rs/v0.4/rocket/fairing/struct.AdHoc.html#method.on_attach\n[`AdHoc::on_launch()`]: https://api.rocket.rs/v0.4/rocket/fairing/struct.AdHoc.html#method.on_launch\n[`Config::root_relative()`]: https://api.rocket.rs/v0.4/rocket/struct.Config.html#method.root_relative\n[`Config::tls_enabled()`]: https://api.rocket.rs/v0.4/rocket/struct.Config.html#method.tls_enabled\n[`rocket_codegen`]: https://api.rocket.rs/v0.4/rocket_codegen/index.html\n[`FromParam`]: https://api.rocket.rs/v0.4/rocket/request/trait.FromParam.html\n[`FromFormValue`]: https://api.rocket.rs/v0.4/rocket/request/trait.FromFormValue.html\n[`Data`]: https://api.rocket.rs/v0.4/rocket/struct.Data.html\n\n## Infrastructure\n\n * All documentation is versioned.\n * Previous, current, and development versions of all documentation are hosted.\n * The repository was reorganized with top-level directories of `core` and\n `contrib`.\n * The `http` module was split into its own `rocket_http` crate. This is an\n internal change only.\n * All uses of `unsafe` are documented with informal proofs of correctness.\n\n# Version 0.3.16 (Aug 24, 2018)\n\n## Codegen\n\n * Codegen was updated for `2018-08-23` nightly.\n * Minimum required `rustc` is `1.30.0-nightly 2018-08-23`.\n\n## Core\n\n * Force close only the read end of connections. This allows responses to be\n sent even when the client transmits more data than expected.\n\n## Docs\n\n * Add details on retrieving configuration extras to guide.\n\n# Version 0.3.15 (Jul 16, 2018)\n\n## Codegen\n\n * The `#[catch]` decorator and `catchers!` macro were introduced, replacing\n `#[error]` and `errors!`.\n * The `#[error]` decorator and `errors!` macro were deprecated.\n * Codegen was updated for `2018-07-15` nightly.\n * Minimum required `rustc` is `1.29.0-nightly 2018-07-15`.\n\n# Version 0.3.14 (Jun 22, 2018)\n\n## Codegen\n\n * Codegen was updated for `2018-06-22` nightly.\n * Minimum required `rustc` is `1.28.0-nightly 2018-06-22`.\n\n# Version 0.3.13 (Jun 16, 2018)\n\n## Codegen\n\n * Codegen was updated for `2018-06-12` nightly.\n * Minimum required `rustc` is `1.28.0-nightly 2018-06-12`.\n\n# Version 0.3.12 (May 31, 2018)\n\n## Codegen\n\n * Codegen was updated for `2018-05-30` nightly.\n * Minimum required `rustc` is `1.28.0-nightly 2018-05-30`.\n\n# Version 0.3.11 (May 19, 2018)\n\n## Core\n\n * Core was updated for `2018-05-18` nightly.\n\n## Infrastructure\n\n * Fixed injection of dependencies for codegen compile-fail tests.\n\n# Version 0.3.10 (May 05, 2018)\n\n## Core\n\n * Fixed parsing of nested TOML structures in config environment variables.\n\n## Codegen\n\n * Codegen was updated for `2018-05-03` nightly.\n * Minimum required `rustc` is `1.27.0-nightly 2018-05-04`.\n\n## Contrib\n\n * Contrib was updated for `2018-05-03` nightly.\n\n## Docs\n\n * Fixed database pool type in state guide.\n\n# Version 0.3.9 (Apr 26, 2018)\n\n## Core\n\n * Core was updated for `2018-04-26` nightly.\n * Minimum required `rustc` is `1.27.0-nightly 2018-04-26`.\n * Managed state retrieval cost was reduced to an unsynchronized `HashMap`\n lookup.\n\n## Codegen\n\n * Codegen was updated for `2018-04-26` nightly.\n * Minimum required `rustc` is `1.27.0-nightly 2018-04-26`.\n\n## Contrib\n\n * A 512-byte buffer is preallocated when deserializing JSON, improving\n performance.\n\n## Docs\n\n * Fixed various typos in rustdocs and guide.\n\n# Version 0.3.8 (Apr 07, 2018)\n\n## Codegen\n\n * Codegen was updated for `2018-04-06` nightly.\n * Minimum required `rustc` is `1.27.0-nightly 2018-04-06`.\n\n# Version 0.3.7 (Apr 03, 2018)\n\n## Core\n\n * Fixed a bug where incoming request URIs would match routes with the same\n path prefix and suffix and ignore the rest.\n * Added known media types for WASM, WEBM, OGG, and WAV.\n * Fixed fragment URI parsing.\n\n## Codegen\n\n * Codegen was updated for `2018-04-03` nightly.\n * Minimum required `rustc` is `1.27.0-nightly 2018-04-03`.\n\n## Contrib\n\n * JSON data is read eagerly, improving deserialization performance.\n\n## Docs\n\n * Database example and docs were updated for Diesel 1.1.\n * Removed outdated README performance section.\n * Fixed various typos in rustdocs and guide.\n\n## Infrastructure\n\n * Removed gates for stabilized features: `iterator_for_each`, `i128_type`,\n `conservative_impl_trait`, `never_type`.\n * Travis now tests in both debug and release mode.\n\n# Version 0.3.6 (Jan 12, 2018)\n\n## Core\n\n * `Rocket.state()` method was added to retrieve managed state from `Rocket`\n instances.\n * Nested calls to `Rocket.attach()` are now handled correctly.\n * JSON API (`application/vnd.api+json`) is now a known media type.\n * Uncached markers for `ContentType` and `Accept` headers are properly\n preserved on `Request.clone()`.\n * Minimum required `rustc` is `1.25.0-nightly 2018-01-12`.\n\n## Codegen\n\n * Codegen was updated for `2017-12-22` nightly.\n * Minimum required `rustc` is `1.24.0-nightly 2017-12-22`.\n\n## Docs\n\n * Fixed typo in state guide: ~~simple~~ simply.\n * Database example and docs were updated for Diesel 1.0.\n\n## Infrastructure\n\n * Shell scripts now use `git grep` instead of `egrep` for faster searching.\n\n# Version 0.3.5 (Dec 18, 2017)\n\n## Codegen\n\n * Codegen was updated for `2017-12-17` nightly.\n * Minimum required `rustc` is `1.24.0-nightly 2017-12-17`.\n\n# Version 0.3.4 (Dec 14, 2017)\n\n## Core\n\n * `NamedFile`'s `Responder` implementation now uses a sized body when the\n file's length is known.\n * `#[repr(C)]` is used on `str` wrappers to guarantee correct structure layout\n across platforms.\n * A `status::BadRequest` `Responder` was added.\n\n## Codegen\n\n * Codegen was updated for `2017-12-13` nightly.\n * Minimum required `rustc` is `1.24.0-nightly 2017-12-13`.\n\n## Docs\n\n * The rustdoc `html_root_url` now points to the correct address.\n * Fixed typo in fairings guide: ~~event~~ events.\n * Fixed typo in `Outcome` docs: ~~users~~ Users.\n\n# Version 0.3.3 (Sep 25, 2017)\n\n## Core\n\n * `Config`'s `Debug` implementation now respects formatting options.\n * `Cow` now implements `FromParam`.\n * `Vec` now implements `Responder`.\n * Added a `Binary` media type for `application/octet-stream`.\n * Empty fairing collections are no longer logged.\n * Emojis are no longer emitted to non-terminals.\n * Minimum required `rustc` is `1.22.0-nightly 2017-09-13`.\n\n## Codegen\n\n * Improved \"missing argument in handler\" compile-time error message.\n * Codegen was updated for `2017-09-25` nightly.\n * Minimum required `rustc` is `1.22.0-nightly 2017-09-25`.\n\n## Docs\n\n * Fixed typos in site overview: ~~by~~ be, ~~`Reponder`~~ `Responder`.\n * Markdown indenting was adjusted for CommonMark.\n\n## Infrastructure\n\n * Shell scripts handle paths with spaces.\n\n# Version 0.3.2 (Aug 15, 2017)\n\n## Core\n\n * Added conversion methods from and to `Box`.\n\n## Codegen\n\n * Lints were removed due to compiler instability. Lints will likely return as\n a separate `rocket_lints` crate.\n\n# Version 0.3.1 (Aug 11, 2017)\n\n## Core\n\n * Added support for ASCII colors on modern Windows consoles.\n * Form field renames can now include _any_ valid characters, not just idents.\n\n## Codegen\n\n * Ignored named route parameters are now allowed (`_ident`).\n * Fixed issue where certain paths would cause a lint `assert!` to fail\n ([#367](https://github.com/rwf2/Rocket/issues/367)).\n * Lints were updated for `2017-08-10` nightly.\n * Minimum required `rustc` is `1.21.0-nightly (2017-08-10)`.\n\n## Contrib\n\n * Tera errors that were previously skipped internally are now emitted.\n\n## Documentation\n\n * Typos were fixed across the board.\n\n# Version 0.3.0 (Jul 14, 2017)\n\n## New Features\n\nThis release includes the following new features:\n\n * [Fairings], Rocket's structure middleware, were introduced.\n * [Native TLS support] was introduced.\n * [Private cookies] were introduced.\n * A [`MsgPack`] type has been added to [`contrib`] for simple consumption and\n returning of MessagePack data.\n * Launch failures ([`LaunchError`]) from [`Rocket::launch()`] are now returned\n for inspection without panicking.\n * Routes without query parameters now match requests with or without query\n parameters.\n * [Default rankings] range from -4 to -1, preferring static paths and routes\n with query string matches.\n * A native [`Accept`] header structure was added.\n * The [`Accept`] request header can be retrieved via [`Request::accept()`].\n * Incoming form fields [can be renamed] via a new `#[form(field = \"name\")]`\n structure field attribute.\n * All active routes can be retrieved via [`Rocket::routes()`].\n * [`Response::body_string()`] was added to retrieve the response body as a\n `String`.\n * [`Response::body_bytes()`] was added to retrieve the response body as a\n `Vec`.\n * [`Response::content_type()`] was added to easily retrieve the Content-Type\n header of a response.\n * Size limits on incoming data are [now\n configurable](https://rocket.rs/v0.3/guide/configuration/#data-limits).\n * [`Request::limits()`] was added to retrieve incoming data limits.\n * Responders may dynamically adjust their response based on the incoming\n request.\n * [`Request::guard()`] was added for simple retrieval of request guards.\n * [`Request::route()`] was added to retrieve the active route, if any.\n * `&Route` is now a request guard.\n * The base mount path of a [`Route`] can be retrieved via `Route::base` or\n `Route::base()`.\n * [`Cookies`] supports _private_ (authenticated encryption) cookies, encrypted\n with the `secret_key` config key.\n * `Config::{development, staging, production}` constructors were added for\n [`Config`].\n * [`Config::get_datetime()`] was added to retrieve an extra as a `Datetime`.\n * Forms can be now parsed _leniently_ via the new [`LenientForm`] data guard.\n * The `?` operator can now be used with `Outcome`.\n * Quoted string, array, and table based [configuration parameters] can be set\n via environment variables.\n * Log coloring is disabled when `stdout` is not a TTY.\n * [`FromForm`] is implemented for `Option`, `Result`.\n * The [`NotFound`] responder was added for simple **404** response\n construction.\n\n[Fairings]: https://rocket.rs/v0.3/guide/fairings/\n[Native TLS support]: https://rocket.rs/v0.3/guide/configuration/#configuring-tls\n[Private cookies]: https://rocket.rs/v0.3/guide/requests/#private-cookies\n[can be renamed]: https://rocket.rs/v0.3/guide/requests/#field-renaming\n[`MsgPack`]: https://api.rocket.rs/v0.3/rocket_contrib/struct.MsgPack.html\n[`Rocket::launch()`]: https://api.rocket.rs/v0.3/rocket/struct.Rocket.html#method.launch\n[`LaunchError`]: https://api.rocket.rs/v0.3/rocket/error/struct.LaunchError.html\n[Default rankings]: https://api.rocket.rs/v0.3/rocket/struct.Route.html\n[`Route`]: https://api.rocket.rs/v0.3/rocket/struct.Route.html\n[`Accept`]: https://api.rocket.rs/v0.3/rocket/http/struct.Accept.html\n[`Request::accept()`]: https://api.rocket.rs/v0.3/rocket/struct.Request.html#method.accept\n[`contrib`]: https://api.rocket.rs/v0.3/rocket_contrib/\n[`Rocket::routes()`]: https://api.rocket.rs/v0.3/rocket/struct.Rocket.html#method.routes\n[`Response::body_string()`]: https://api.rocket.rs/v0.3/rocket/struct.Response.html#method.body_string\n[`Response::body_bytes()`]: https://api.rocket.rs/v0.3/rocket/struct.Response.html#method.body_bytes\n[`Response::content_type()`]: https://api.rocket.rs/v0.3/rocket/struct.Response.html#method.content_type\n[`Request::guard()`]: https://api.rocket.rs/v0.3/rocket/struct.Request.html#method.guard\n[`Request::limits()`]: https://api.rocket.rs/v0.3/rocket/struct.Request.html#method.limits\n[`Request::route()`]: https://api.rocket.rs/v0.3/rocket/struct.Request.html#method.route\n[`Config`]: https://api.rocket.rs/v0.3/rocket/struct.Config.html\n[`Cookies`]: https://api.rocket.rs/v0.3/rocket/http/enum.Cookies.html\n[`Config::get_datetime()`]: https://api.rocket.rs/v0.3/rocket/struct.Config.html#method.get_datetime\n[`LenientForm`]: https://api.rocket.rs/v0.3/rocket/request/struct.LenientForm.html\n[configuration parameters]: https://api.rocket.rs/v0.3/rocket/config/index.html#environment-variables\n[`NotFound`]: https://api.rocket.rs/v0.3/rocket/response/status/struct.NotFound.html\n\n## Breaking Changes\n\nThis release includes many breaking changes. These changes are listed below\nalong with a short note about how to handle the breaking change in existing\napplications.\n\n * **`session_key` was renamed to `secret_key`, requires a 256-bit base64 key**\n\n It's unlikely that `session_key` was previously used. If it was, rename\n `session_key` to `secret_key`. Generate a random 256-bit base64 key using a\n tool like openssl: `openssl rand -base64 32`.\n\n * **The `&Cookies` request guard has been removed in favor of `Cookies`**\n\n Change `&Cookies` in a request guard position to `Cookies`.\n\n * **`Rocket::launch()` now returns a `LaunchError`, doesn't panic.**\n\n For the old behavior, suffix a call to `.launch()` with a semicolon:\n `.launch();`.\n\n * **Routes without query parameters match requests with or without query\n parameters.**\n\n There is no workaround, but this change may allow manual ranks from routes\n to be removed.\n\n * **The `format` route attribute on non-payload requests matches against the\n Accept header.**\n\n Excepting a custom request guard, there is no workaround. Previously,\n `format` always matched against the Content-Type header, regardless of\n whether the request method indicated a payload or not.\n\n * **A type of `&str` can no longer be used in form structures or parameters.**\n\n Use the new [`&RawStr`] type instead.\n\n * **`ContentType` is no longer a request guard.**\n\n Use `&ContentType` instead.\n\n * **`Request::content_type()` returns `&ContentType` instead of\n `ContentType`.**\n\n Use `.clone()` on `&ContentType` if a type of `ContentType` is required.\n\n * **`Response::header_values()` was removed. `Response::headers()` now returns\n an `&HeaderMap`.**\n\n A call to `Response::headers()` can be replaced with\n `Response::headers().iter()`. A call to `Response::header_values(name)` can\n be replaced with `Response::headers().get(name)`.\n\n * **Route collisions result in a hard error and panic.**\n\n There is no workaround. Previously, route collisions were a warning.\n\n * **The [`IntoOutcome`] trait has been expanded and made more flexible.**\n\n There is no workaround. `IntoOutcome::into_outcome()` now takes a `Failure`\n value to use. `IntoOutcome::or_forward()` was added to return a `Forward`\n outcome if `self` indicates an error.\n\n * **The 'testing' feature was removed.**\n\n Remove `features = [\"testing\"]` from `Cargo.toml`. Use the new [`local`]\n module for testing.\n\n * **`serde` was updated to 1.0.**\n\n There is no workaround. Ensure all dependencies rely on `serde` `1.0`.\n\n * **`config::active()` was removed.**\n\n Use [`Rocket::config()`] to retrieve the configuration before launch. If\n needed, use [managed state] to store config information for later use.\n\n * **The [`Responder`] trait has changed.**\n\n `Responder::respond(self)` was removed in favor of\n `Responder::respond_to(self, &Request)`. Responders may dynamically adjust\n their response based on the incoming request.\n\n * **`Outcome::of(Responder)` was removed while `Outcome::from(&Request,\n Responder)` was added.**\n\n Use `Outcome::from(..)` instead of `Outcome::of(..)`.\n\n * **Usage of templates requires `Template::fairing()` to be attached.**\n\n Call `.attach(Template::fairing())` on the application's Rocket instance\n before launching.\n\n * **The `Display` implementation of `Template` was removed.**\n\n Use [`Template::show()`] to render a template directly.\n\n * **`Request::new()` is no longer exported.**\n\n There is no workaround.\n\n * **The [`FromForm`] trait has changed.**\n\n `Responder::from_form_items(&mut FormItems)` was removed in favor of\n `Responder::from_form(&mut FormItems, bool)`. The second parameter indicates\n whether parsing should be strict (if `true`) or lenient (if `false`).\n\n * **`LoggingLevel` was removed as a root reexport.**\n\n It can now be imported from `rocket::config::LoggingLevel`.\n\n * **An `Io` variant was added to [`ConfigError`].**\n\n Ensure `match`es on `ConfigError` include an `Io` variant.\n\n * **[`ContentType::from_extension()`] returns an `Option`.**\n\n For the old behavior, use `.unwrap_or(ContentType::Any)`.\n\n * **The `IntoValue` config trait was removed in favor of `Into`.**\n\n There is no workaround. Use `Into` as necessary.\n\n * **The `rocket_contrib::JSON` type has been renamed to\n [`rocket_contrib::Json`].**\n\n Use `Json` instead of `JSON`.\n\n * **All structs in the [`content`] module use TitleCase names.**\n\n Use `Json`, `Xml`, `Html`, and `Css` instead of `JSON`, `XML`, `HTML`, and\n `CSS`, respectively.\n\n[`&RawStr`]: https://api.rocket.rs/v0.3/rocket/http/struct.RawStr.html\n[`IntoOutcome`]: https://api.rocket.rs/v0.3/rocket/outcome/trait.IntoOutcome.html\n[`local`]: https://api.rocket.rs/v0.3/rocket/local/index.html\n[`Rocket::config()`]: https://api.rocket.rs/v0.3/rocket/struct.Rocket.html#method.config\n[managed state]: https://rocket.rs/v0.3/guide/state/\n[`Responder`]: https://api.rocket.rs/v0.3/rocket/response/trait.Responder.html\n[`Template::show()`]: https://api.rocket.rs/v0.3/rocket_contrib/struct.Template.html#method.show\n[`FromForm`]: https://api.rocket.rs/v0.3/rocket/request/trait.FromForm.html\n[`ConfigError`]: https://api.rocket.rs/v0.3/rocket/config/enum.ConfigError.html\n[`ContentType::from_extension()`]: https://api.rocket.rs/v0.3/rocket/http/struct.ContentType.html#method.from_extension\n[`rocket_contrib::Json`]: https://api.rocket.rs/v0.3/rocket_contrib/struct.Json.html\n[`content`]: https://api.rocket.rs/v0.3/rocket/response/content/index.html\n\n## General Improvements\n\nIn addition to new features, Rocket saw the following improvements:\n\n * \"Rocket\" is now capitalized in the `Server` HTTP header.\n * The generic parameter of `rocket_contrib::Json` defaults to `json::Value`.\n * The trailing '...' in the launch message was removed.\n * The launch message prints regardless of the config environment.\n * For debugging, `FromData` is implemented for `Vec` and `String`.\n * The port displayed on launch is the port resolved, not the one configured.\n * The `uuid` dependency was updated to `0.5`.\n * The `base64` dependency was updated to `0.6`.\n * The `toml` dependency was updated to `0.4`.\n * The `handlebars` dependency was updated to `0.27`.\n * The `tera` dependency was updated to `0.10`.\n * [`yansi`] is now used for all terminal coloring.\n * The `dev` `rustc` release channel is supported during builds.\n * [`Config`] is now exported from the root.\n * [`Request`] implements `Clone` and `Debug`.\n * The `workers` config parameter now defaults to `num_cpus * 2`.\n * Console logging for table-based config values is improved.\n * `PartialOrd`, `Ord`, and `Hash` are now implemented for [`State`].\n * The format of a request is always logged when available.\n * Route matching on `format` now functions as documented.\n\n[`yansi`]: https://crates.io/crates/yansi\n[`Request`]: https://api.rocket.rs/v0.3/rocket/struct.Request.html\n[`State`]: https://api.rocket.rs/v0.3/rocket/struct.State.html\n\n## Infrastructure\n\n * All examples include a test suite.\n * The `master` branch now uses a `-dev` version number.\n\n# Version 0.2.8 (Jun 01, 2017)\n\n## Codegen\n\n * Lints were updated for `2017-06-01` nightly.\n * Minimum required `rustc` is `1.19.0-nightly (2017-06-01)`.\n\n# Version 0.2.7 (May 26, 2017)\n\n## Codegen\n\n * Codegen was updated for `2017-05-26` nightly.\n\n# Version 0.2.6 (Apr 17, 2017)\n\n## Codegen\n\n * Allow `k` and `v` to be used as fields in `FromForm` structures by avoiding\n identifier collisions ([#265]).\n\n[#265]: https://github.com/rwf2/Rocket/issues/265\n\n# Version 0.2.5 (Apr 16, 2017)\n\n## Codegen\n\n * Lints were updated for `2017-04-15` nightly.\n * Minimum required `rustc` is `1.18.0-nightly (2017-04-15)`.\n\n# Version 0.2.4 (Mar 30, 2017)\n\n## Codegen\n\n * Codegen was updated for `2017-03-30` nightly.\n * Minimum required `rustc` is `1.18.0-nightly (2017-03-30)`.\n\n# Version 0.2.3 (Mar 22, 2017)\n\n## Fixes\n\n * Multiple header values for the same header name are now properly preserved\n (#223).\n\n## Core\n\n * The `get_slice` and `get_table` methods were added to `Config`.\n * The `pub_restricted` feature has been stabilized!\n\n## Codegen\n\n * Lints were updated for `2017-03-20` nightly.\n * Minimum required `rustc` is `1.17.0-nightly (2017-03-22)`.\n\n## Infrastructure\n\n * The test script now denies trailing whitespace.\n\n# Version 0.2.2 (Feb 26, 2017)\n\n## Codegen\n\n * Lints were updated for `2017-02-25` and `2017-02-26` nightlies.\n * Minimum required `rustc` is `1.17.0-nightly (2017-02-26)`.\n\n# Version 0.2.1 (Feb 24, 2017)\n\n## Core Fixes\n\n * `Flash` cookie deletion functions as expected regardless of the path.\n * `config` properly accepts IPv6 addresses.\n * Multiple `Set-Cookie` headers are properly set.\n\n## Core Improvements\n\n * `Display` and `Error` were implemented for `ConfigError`.\n * `webp`, `ttf`, `otf`, `woff`, and `woff2` were added as known content types.\n * Routes are presorted for faster routing.\n * `into_bytes` and `into_inner` methods were added to `Body`.\n\n## Codegen\n\n * Fixed `unmanaged_state` lint so that it works with prefilled type aliases.\n\n## Contrib\n\n * Better errors are emitted on Tera template parse errors.\n\n## Documentation\n\n * Fixed typos in `manage` and `JSON` docs.\n\n## Infrastructure\n\n * Updated doctests for latest Cargo nightly.\n\n# Version 0.2.0 (Feb 06, 2017)\n\nDetailed release notes for v0.2 can also be found on\n[rocket.rs](https://rocket.rs/v0.3/news/2017-02-06-version-0.2/).\n\n## New Features\n\nThis release includes the following new features:\n\n * Introduced managed state.\n * Added lints that warn on unmanaged state and unmounted routes.\n * Added the ability to set configuration parameters via environment variables.\n * `Config` structures can be built via `ConfigBuilder`, which follows the\n builder pattern.\n * Logging can be enabled or disabled on custom configuration via a second\n parameter to the `Rocket::custom` method.\n * `name` and `value` methods were added to `Header` to retrieve the name and\n value of a header.\n * A new configuration parameter, `workers`, can be used to set the number of\n threads Rocket uses.\n * The address of the remote connection is available via `Request.remote()`.\n Request preprocessing overrides remote IP with value from the `X-Real-IP`\n header, if present.\n * During testing, the remote address can be set via `MockRequest.remote()`.\n * The `SocketAddr` request guard retrieves the remote address.\n * A `UUID` type has been added to `contrib`.\n * `rocket` and `rocket_codegen` will refuse to build with an incompatible\n nightly version and emit nice error messages.\n * Major performance and usability improvements were upstreamed to the `cookie`\n crate, including the addition of a `CookieBuilder`.\n * When a checkbox isn't present in a form, `bool` types in a `FromForm`\n structure will parse as `false`.\n * The `FormItems` iterator can be queried for a complete parse via `completed`\n and `exhausted`.\n * Routes for `OPTIONS` requests can be declared via the `options` decorator.\n * Strings can be percent-encoded via `URI::percent_encode()`.\n\n## Breaking Changes\n\nThis release includes several breaking changes. These changes are listed below\nalong with a short note about how to handle the breaking change in existing\napplications.\n\n * **`Rocket::custom` takes two parameters, the first being `Config` by\n value.**\n\n A call in v0.1 of the form `Rocket::custom(&config)` is now\n `Rocket::custom(config, false)`.\n\n * **Tera templates are named without their extension.**\n\n A templated named `name.html.tera` is now simply `name`.\n\n * **`JSON` `unwrap` method has been renamed to `into_inner`.**\n\n A call to `.unwrap()` should be changed to `.into_inner()`.\n\n * **The `map!` macro was removed in favor of the `json!` macro.**\n\n A call of the form `map!{ \"a\" => b }` can be written as: `json!({ \"a\": b\n })`.\n\n * **The `hyper::SetCookie` header is no longer exported.**\n\n Use the `Cookie` type as an `Into

` type directly.\n\n * **The `Content-Type` for `String` is now `text/plain`.**\n\n Use `content::HTML` for HTML-based `String` responses.\n\n * **`Request.content_type()` returns an `Option`.**\n\n Use `.unwrap_or(ContentType::Any)` to get the old behavior.\n\n * **The `ContentType` request guard forwards when the request has no\n `Content-Type` header.**\n\n Use an `Option` and `.unwrap_or(ContentType::Any)` for the old\n behavior.\n\n * **A `Rocket` instance must be declared _before_ a `MockRequest`.**\n\n Change the order of the `rocket::ignite()` and `MockRequest::new()` calls.\n\n * **A route with `format` specified only matches requests with the same\n format.**\n\n Previously, a route with a `format` would match requests without a format\n specified. There is no workaround to this change; simply specify formats\n when required.\n\n * **`FormItems` can no longer be constructed directly.**\n\n Instead of constructing as `FormItems(string)`, construct as\n `FormItems::from(string)`.\n\n * **`from_from_string(&str)` in `FromForm` removed in favor of\n `from_form_items(&mut FormItems)`.**\n\n Most implementation should be using `FormItems` internally; simply use the\n passed in `FormItems`. In other cases, the form string can be retrieved via\n the `inner_str` method of `FormItems`.\n\n * **`Config::{set, default_for}` are deprecated.**\n\n Use the `set_{param}` methods instead of `set`, and `new` or `build` in\n place of `default_for`.\n\n * **Route paths must be absolute.**\n\n Prepend a `/` to convert a relative path into an absolute one.\n\n * **Route paths cannot contain empty segments.**\n\n Remove any empty segments, including trailing ones, from a route path.\n\n## Bug Fixes\n\nA couple of bugs were fixed in this release:\n\n * Handlebars partials were not properly registered\n ([#122](https://github.com/rwf2/Rocket/issues/122)).\n * `Rocket::custom` did not set the custom configuration as the `active`\n configuration.\n * Route path segments containing more than one dynamic parameter were\n allowed.\n\n## General Improvements\n\nIn addition to new features, Rocket saw the following smaller improvements:\n\n * Rocket no longer overwrites a catcher's response status.\n * The `port` `Config` type is now a proper `u16`.\n * Clippy issues injected by codegen are resolved.\n * Handlebars was updated to `0.25`.\n * The `PartialEq` implementation of `Config` doesn't consider the path or\n secret key.\n * Hyper dependency updated to `0.10`.\n * The `Error` type for `JSON as FromData` has been exposed as `SerdeError`.\n * SVG was added as a known Content-Type.\n * Serde was updated to `0.9`.\n * Form parse failure now results in a **422** error code.\n * Tera has been updated to `0.7`.\n * `pub(crate)` is used throughout to enforce visibility rules.\n * Query parameters in routes (`/path?`) are now logged.\n * Routes with and without query parameters no longer _collide_.\n\n## Infrastructure\n\n * Testing was parallelized, resulting in 3x faster Travis builds.\n\n# Version 0.1.6 (Jan 26, 2017)\n\n## Infrastructure\n\n * Hyper version pinned to 0.9.14 due to upstream non-semver breaking change.\n\n# Version 0.1.5 (Jan 14, 2017)\n\n## Core\n\n * Fixed security checks in `FromSegments` implementation for `PathBuf`.\n\n## Infrastructure\n\n * `proc_macro` feature removed from examples due to stability.\n\n# Version 0.1.4 (Jan 4, 2017)\n\n## Core\n\n * Header names are treated as case-preserving.\n\n## Codegen\n\n * Minimum supported nightly is `2017-01-03`.\n\n# Version 0.1.3 (Dec 31, 2016)\n\n## Core\n\n * Typo in `Outcome` formatting fixed (Succcess -> Success).\n * Added `ContentType::CSV`.\n * Dynamic segments parameters are properly resolved, even when mounted.\n * Request methods are only overridden via `_method` field on POST.\n * Form value `String`s are properly decoded.\n\n## Codegen\n\n * The `_method` field is now properly ignored in `FromForm` derivation.\n * Unknown Content-Types in `format` no longer result in an error.\n * Deriving `FromForm` no longer results in a deprecation warning.\n * Codegen will refuse to build with incompatible rustc, presenting error\n message and suggestion.\n * Added `head` as a valid decorator for `HEAD` requests.\n * Added `route(OPTIONS)` as a valid decorator for `OPTIONS` requests.\n\n## Contrib\n\n * Templates with the `.tera` extension are properly autoescaped.\n * Nested template names are properly resolved on Windows.\n * Template implements `Display`.\n * Tera dependency updated to version 0.6.\n\n## Docs\n\n * Todo example requirements clarified in its `README`.\n\n## Testing\n\n * Tests added for `config`, `optional_result`, `optional_redirect`, and\n `query_params` examples.\n * Testing script checks for and disallows tab characters.\n\n## Infrastructure\n\n * New script (`bump_version.sh`) automates version bumps.\n * Config script emits error when readlink/readpath support is bad.\n * Travis badge points to public builds.\n\n# Version 0.1.2 (Dec 24, 2016)\n\n## Codegen\n\n * Fix `get_raw_segments` index argument in route codegen\n ([#41](https://github.com/rwf2/Rocket/issues/41)).\n * Segments params (``) respect prefixes.\n\n## Contrib\n\n * Fix nested template name resolution\n ([#42](https://github.com/rwf2/Rocket/issues/42)).\n\n## Infrastructure\n\n * New script (`publish.sh`) automates publishing to crates.io.\n * New script (`bump_version.sh`) automates version bumps.\n\n# Version 0.1.1 (Dec 23, 2016)\n\n## Core\n\n * `NamedFile` `Responder` lost its body in the shuffle; it's back!\n\n# Version 0.1.0 (Dec 23, 2016)\n\nThis is the first public release of Rocket!\n\n## Breaking\n\nAll of the mentions to `hyper` types in core Rocket types are no more. Rocket\nnow implements its own `Request` and `Response` types.\n\n * `ContentType` uses associated constants instead of static methods.\n * `StatusCode` removed in favor of new `Status` type.\n * `Response` type alias superseded by `Response` type.\n * `Responder::respond` no longer takes in hyper type.\n * `Responder::respond` returns `Response`, takes `self` by move.\n * `Handler` returns `Outcome` instead of `Response` type alias.\n * `ErrorHandler` returns `Result`.\n * All `Hyper*` types were moved to unprefixed versions in `hyper::`.\n * `MockRequest::dispatch` now returns a `Response` type.\n * `URIBuf` removed in favor of unified `URI`.\n * Rocket panics when an illegal, dynamic mount point is used.\n\n## Core\n\n * Rocket handles `HEAD` requests automatically.\n * New `Response` and `ResponseBuilder` types.\n * New `Request`, `Header`, `Status`, and `ContentType` types.\n\n## Testing\n\n * `MockRequest` allows any type of header.\n * `MockRequest` allows cookies.\n\n## Codegen\n\n * Debug output disabled by default.\n * The `ROCKET_CODEGEN_DEBUG` environment variables enables codegen logging.\n\n# Version 0.0.11 (Dec 11, 2016)\n\n## Streaming Requests\n\nAll incoming request data is now streamed. This resulted in a major change to\nthe Rocket APIs. They are summarized through the following API changes:\n\n * The `form` route parameter has been removed.\n * The `data` route parameter has been introduced.\n * Forms are now handled via the `data` parameter and `Form` type.\n * Removed the `data` parameter from `Request`.\n * Added `FromData` conversion trait and default implementation.\n * `FromData` is used to automatically derive the `data` parameter.\n * `Responder`s are now final: they cannot forward to other requests.\n * `Responder`s may only forward to catchers.\n\n## Breaking\n\n * Request `uri` parameter is private. Use `uri()` method instead.\n * `form` module moved under `request` module.\n * `response::data` was renamed to `response::content`.\n * Introduced `Outcome` with `Success`, `Failure`, and `Forward` variants.\n * `outcome` module moved to top-level.\n * `Response` is now a type alias to `Outcome`.\n * `Empty` `Responder` was removed.\n * `StatusResponder` removed in favor of `response::status` module.\n\n## Codegen\n\n * Error handlers can now take 0, 1, or 2 parameters.\n * `FromForm` derive now works on empty structs.\n * Lifetimes are now properly stripped in code generation.\n * Any valid ident is now allowed in single-parameter route parameters.\n\n## Core\n\n * Route is now cloneable.\n * `Request` no longer has any lifetime parameters.\n * `Handler` type now includes a `Data` parameter.\n * `http` module is public.\n * `Responder` implemented for `()` type as an empty response.\n * Add `config::get()` for global config access.\n * Introduced `testing` module.\n * `Rocket.toml` allows global configuration via `[global]` table.\n\n## Docs\n\n * Added a `raw_upload` example.\n * Added a `pastebin` example.\n * Documented all public APIs.\n\n## Testing\n\n * Now building and running tests with `--all-features` flag.\n * Added appveyor config for Windows CI testing.\n\n# Version 0.0.10 (Oct 03, 2016)\n\n## Breaking\n\n * Remove `Rocket::new` in favor of `ignite` method.\n * Remove `Rocket::mount_and_launch` in favor of chaining `mount(..).launch()`.\n * `mount` and `catch` take `Rocket` type by value.\n * All types related to HTTP have been moved into `http` module.\n * `Template::render` in `contrib` now takes context by reference.\n\n## Core\n\n * Rocket now parses option `Rocket.toml` for configuration, defaulting to sane\n values.\n * `ROCKET_ENV` environment variable can be used to specify running environment.\n\n## Docs\n\n * Document `ContentType`.\n * Document `Request`.\n * Add script that builds docs.\n\n## Testing\n\n * Scripts can now be run from any directory.\n * Cache Cargo directories in Travis for faster testing.\n * Check that library version numbers match in testing script.\n\n# Version 0.0.9 (Sep 29, 2016)\n\n## Breaking\n\n * Rename `response::data_type` to `response::data`.\n\n## Core\n\n * Rocket interprets `_method` field in forms as the incoming request's method.\n * Add `Outcome::Bad` to signify responses that failed internally.\n * Add a `NamedFile` `Responder` type that uses a file's extension for the\n response's content type.\n * Add a `Stream` `Responder` for streaming responses.\n\n## Contrib\n\n * Introduce the `contrib` crate.\n * Add JSON support via `JSON`, which implements `FromRequest` and `Responder`.\n * Add templating support via `Template` which implements `Responder`.\n\n## Docs\n\n * Initial guide-like documentation.\n * Add documentation, testing, and contributing sections to README.\n\n## Testing\n\n * Add a significant number of codegen tests.\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to Rocket\n\n**Please read this document before contributing!**\n\nThank you for contributing! We welcome your contributions in whichever form they\nmay come.\n\nThis document provides guidelines and resources to help you successfully\ncontribute to the project. Rocket is a tool designed to push the envelope of\nusability, security, _and_ performance in web frameworks, and accordingly, our\nquality standards are high. To make the best use of everyone's time and avoid\nwasted efforts, take a moment to understand our expectations and conventions\noutlined here.\n\n## Submitting Pull Requests\n\nBefore creating a new pull request:\n\n * Read and understand [Code Style Conventions], [Commit Message Guidelines],\n and [Testing].\n * If you're resolving an open issue, follow [Resolving an Open Issue].\n * If you're implementing new functionality, check whether the functionality\n you're implementing has been proposed before, either as an [issue] or [pull\n request]. Ensure your PR resolves any previously raised concerns. Then,\n follow [Implementing an Unproposed Feature].\n * For everything else, see [Other Common Contributions].\n\nWe aim to keep Rocket's code quality at the highest level. This means that any\ncode you contribute must be:\n\n * **Commented:** Complex or subtle functionality must be properly commented.\n * **Documented:** Public items must have doc comments with examples.\n * **Styled:** Your code must follow the [Code Style Conventions].\n * **Simple:** Your code should accomplish its task as simply and\n idiomatically as possible.\n * **Tested:** You must write (and pass) convincing [tests](#testing) for all\n new or changed functionality.\n * **Focused:** Your code should do what it's supposed to and nothing more.\n\n### Resolving an Open Issue\n[Resolving an Open Issue]: #resolving-an-open-issue\n\nIf you spot an open issue that you'd like to resolve:\n\n 1. **First identify if there's a proposed solution to the problem.**\n\n If there is, proceed to step 2. If there isn't, your first course of\n action, before writing any code, is to propose a solution. To do so, leave\n a comment describing your solution in the relevant issue. It's especially\n useful to see test cases and hypothetical examples. This step is critical:\n it allows us to identify and resolve concerns with a proposed solution\n before anyone spends time writing code. It may also allow us to point you\n in more efficient implementation directions.\n\n 2. **Write a failing test case you expect to pass after resolving the issue.**\n\n If you can write proper tests cases that fail, do so (see [Testing]). If\n you cannot, for instance because you're introducing new APIs which can't be\n used until they exist, write a test case that mocks usage of those APIs. In\n either case, allow the tests and mock examples to guide your progress.\n\n 3. **Write basic functionality, pass tests, and submit a PR.**\n\n Think about edge cases to the problem and ensure you have tests for those\n edge cases. Once your implementation is functionally complete, submit a PR.\n Don't spend time writing or changing a bunch of documentation just yet.\n\n 4. **Wait for a review, iterate, and polish.**\n\n If a review doesn't come in a few days, feel free to ping a maintainer.\n Once someone reviews your PR, integrate their feedback. If the PR solves the\n issue (which it should because you have passing tests) and fits the project\n (which it should since you sought feedback _before_ submitting), it will be\n _conditionally_ approved pending final polish: documentation (rustdocs,\n guide docs), style improvements, and testing. Your PR will then be merged.\n\n### Implementing an Unproposed Feature\n[Implementing an Unproposed Feature]: #implementing-an-unproposed-feature\n\nFirst and foremost, **please do not submit a PR that implements a new feature\nwithout first proposing a design and seeking feedback.** We take the addition of\nnew features _very_ seriously because they directly impact usability.\n\nTo propose a new feature, create a [new feature request issue] and follow the\ntemplate. Note that certain classes of features require particularly compelling\njustification to be taken into consideration. These include features that:\n\n * Can be implemented outside of Rocket.\n * Introduce new dependencies, especially heavier ones.\n * Only exist to add support for an external crate.\n * Are too specific to one use-case.\n * Are overtly complex _and_ have \"simple\" workarounds.\n * Only partially solve a bigger deficiency.\n\nOnce your feature request is accepted, follow [Resolving an Open Issue].\n\n[new feature request issue]: https://github.com/rwf2/Rocket/issues/new?assignees=&labels=request&projects=&template=feature-request.yml\n\n### Other Common Contributions\n[Other Common Contributions]: #other-common-contributions\n\n * **Doc fixes, typos, wording improvements.**\n\n We encourage any of these! Just a submit a PR with your changes. Please\n preserve the surrounding markdown formatting as much as possible. This\n typically means keeping lines under 80 characters, keeping table delimiters\n aligned, and preserving indentation accordingly.\n\n The guide's source files are at [docs/guide]. Note the following special\n syntax available in guide markdown:\n\n - **Cross-linking** pages is accomplished via relative links. Outside\n of the index, this is: `../{page}#anchor`. For instance, to link to\n **Quickstart > Running Examples**, use `../quickstart#running-examples`.\n - **Aliases** are shorthand URLs that start with `@` (e.g, `@api`). They are\n used throughout the guide to simplify creating versioned URLs. They are\n replaced at build time with the appropriate versioned instance.\n\n * **New examples or changes to existing ones.**\n\n Please follow the [Implementing an Unproposed Feature] process.\n\n * **Formatting or other purely cosmetic changes.**\n\n We generally do not accept purely cosmetic changes to the codebase such as\n style or formatting changes. All PRs must add something substantial to\n Rocket's functionality, coherence, testing, performance, usability, bug\n fixes, security, documentation, or overall maintainability.\n\n * **Advertisements of any nature.**\n\n We do not accept any contributions that resemble advertisements or\n promotional content. If you are interested in supporting Rocket, we\n encourage you to [sponsor the project].\n\n## Testing\n[Testing]: #testing\n\nAll testing happens through [test.sh]. Before submitting a PR, run the script\nand fix any issues. The default mode (passing no arguments or `--default`) will\nusually suffice, but you may also wish to execute additional tests. In\nparticular:\n\n * If you make changes to `contrib`: `test.sh --contrib`\n * If you make user-facing API changes or update deps: `test.sh --examples`\n * If you add or modify feature flags: `test.sh --core`\n * If you modify codegen: see [UI Tests].\n\nRun `test.sh --help` to get an overview of how to execute the script:\n\n```sh\nUSAGE:\n ./scripts/test.sh [+] [--help|-h] [--]\n\nOPTIONS:\n + Forwarded to Cargo to select toolchain.\n --help, -h Print this help message and exit.\n -- Run the specified test suite.\n (Run without -- to run default tests.)\n\nAVAILABLE OPTIONS:\n default\n all\n core\n contrib\n examples\n benchmarks\n testbench\n ui\n\nEXAMPLES:\n ./scripts/test.sh # Run default tests on current toolchain.\n ./scripts/test.sh +stable --all # Run all tests on stable toolchain.\n ./scripts/test.sh --ui # Run UI tests on current toolchain.\n```\n\n### Writing Tests\n\nRocket is tested in a variety of ways. This includes via Rust's regular testing\nfacilities such as doctests, unit tests, and integration tests, as well Rocket's\nexamples, testbench, and [UI Tests]:\n\n - **Examples**: The [`examples`](examples/) directory contains applications\n that make use of many of Rocket's features. Each example is integration\n tested using Rocket's built-in [local testing]. This both ensures that\n typical Rocket code continues to work as expected and serves as a way to\n detect and resolve user-facing breaking changes.\n\n - **Testbench**: Rocket's [testbench](testbench/) tests end-to-end server or\n protocol properties by starting up full Rocket servers to which it\n dispatches real HTTP requests. Each server is independently written in\n [testbench/src/servers/](testbench/src/servers/). You're unlikely to need to\n write a testbench test unless you're modifying low-level details.\n\n - **UI Tests**: UI tests ensure Rocket's codegen produces meaningful compiler\n diagnostics. They compile Rocket applications and compare the compiler's\n output to expected results. If you're changing codegen, you'll need to\n update or create UI tests. See [UI Tests] for details.\n\nFor any change that affects functionality, we ask that you write a test that\nverifies that functionality. Minimally, this means a unit test, doctest,\nintegration test, or some combination of these. For small changes, unit tests\nwill likely suffice. If the change affects the user in any way, then doctests\nshould be added or modified. And if the change requires using unrelated APIs to\ntest, then an integration test should be added.\n\nAdditionally, the following scenarios require special attention:\n\n - **Improved Features**\n\n Modifying an existing example is a great place to write tests for improved\n features. If you do modify an example, make sure you modify the README in\n the example directory, too.\n\n - **New Features**\n\n For major features, introducing a new example that showcases idiomatic use\n of the feature can be useful. Make sure you modify the README in the\n `examples` directory if you do. In addition, all newly introduced public\n APIs should be fully documented and include doctests as well as unit and\n integration tests.\n\n - **Fixing a Bug**\n\n To avoid regressions, _always_ introduce or modify an integration or\n testbench test for a bugfix. Integration tests should live in the usual\n `tests/` directory and be named `short-issue-description-NNNN.rs`, where\n `NNNN` is the GitHub issue number for the bug. For example,\n `forward-includes-status-1560.rs`.\n\n[local testing]: https://api.rocket.rs/master/rocket/local/\n\n### UI Tests\n[UI Tests]: #ui-tests\n\nChanges to codegen (i.e, `rocket_codegen` and other `_codegen` crates)\nnecessitate adding and running UI tests, which capture compiler output and\ncompare it against some expected output. UI tests use [`trybuild`].\n\nTests can be found in the `codegen/tests/ui-fail` directories of respective\n`codegen` crates. Each test is symlinked into sibling `ui-fail-stable` and\n`ui-fail-nightly` directories, which also contain the expected error output for\nstable and nightly compilers, respectively. For example:\n\n```\n./core/codegen/tests\n├── ui-fail\n│   ├── async-entry.rs\n│   ├── ...\n│   └── uri_display_type_errors.rs\n├── ui-fail-nightly\n│   ├── async-entry.rs -> ../ui-fail/async-entry.rs\n│   ├── async-entry.stderr\n│   ├── ...\n│   ├── uri_display_type_errors.rs -> ../ui-fail/uri_display_type_errors.rs\n│   └── uri_display_type_errors.stderr\n└── ui-fail-stable\n    ├── async-entry.rs -> ../ui-fail/async-entry.rs\n    ├── async-entry.stderr\n    ├── ...\n    ├── uri_display_type_errors.rs -> ../ui-fail/uri_display_type_errors.rs\n    └── uri_display_type_errors.stderr\n```\n\nIf you make changes to codegen, run the UI tests for stable and nightly with\n`test.sh +stable --ui` and `test.sh +nightly --ui`. If there are failures,\nupdate the outputs with `TRYBUILD=overwrite test.sh +nightly --ui` and\n`TRYBUILD=overwrite test.sh +stable --ui`. Look at the diff to see what's\nchanged. Ensure that error messages properly attribute (i.e., visually underline\nor point to) the source of the error. For example, if a type need to implement a\ntrait, then that type should be underlined. We strive to emit the most helpful\nand descriptive error messages possible.\n\n### API Docs\n\nIf you make changes to documentation, you should build the API docs and verify\nthat your changes look as you expect. API documentation is built with\n[mk-docs.sh] and output to the usual `target/docs` directory. By default, the\nscript will `clean` any existing docs to avoid potential caching issues. To\noverride this behavior, use `mk-docs.sh -d`.\n\n## Code Style Conventions\n[Code Style Conventions]: #code-style-conventions\n\nWe _do not_ use `rustfmt` or `cargo fmt` due to bugs and missing functionality.\nInstead, we ask that you follow the [Rust Style Guide] with the following\nchanges:\n\n**Always separate items with one blank line.**\n\n\n\n \n \n \n \n\n\n \n \n\n\n\n
✅ YesNo 🚫
\n\n```rust\nfn foo() {\n // ..\n}\n\nfn bar() {\n // ..\n}\n```\n\n\n\n```rust\nfn foo() {\n // ..\n}\nfn bar() {\n // ..\n}\n```\n\n
\n\n**Prefer a where-clause over block-indented generics.**\n\n\n\n \n \n \n \n\n\n \n \n\n\n\n
✅ YesNo 🚫
\n\n```rust\nfn foo(x: Vec, y: Vec)\n where T: Display, U: Debug\n{\n // ..\n}\n```\n\n\n\n```rust\nfn foo<\n T: Display,\n U: Debug,\n>(x: Vec, y: Vec) {\n // ..\n}\n```\n\n
\n\n**For \"short\" where-clauses, follow Rust guidelines. For \"long\" where-clauses,\nblock-indent `where`, place the first bound on the same line as `where`, and\nblock-align the remaining bounds.**\n\n\n\n \n \n \n \n\n\n \n \n\n\n\n
✅ YesNo 🚫
\n\n```rust\nfn foo(v: Foo) -> G\n where T: for<'x> SomeTrait<'x>\n F: Fn(Item) -> G,\n Item: Display + Debug,\n G: Error,\n{\n // ..\n}\n```\n\n\n\n```rust\nfn foo(v: Foo) -> G\n where\n T: for<'x> SomeTrait<'x>\n F: Fn(Item) -> G,\n Item: Display + Debug,\n G: Error,\n{\n // ..\n}\n```\n\n
\n\n**Do not use multi-line imports. Use multiple lines grouped by import kind if\npossible.**\n\n\n\n \n \n \n \n\n\n \n \n\n\n\n
✅ YesNo 🚫
\n\n```rust\nuse foo::{Long, List, Of, Type, Imports};\nuse foo::{some_macro, imports};\n```\n\n\n\n```rust\nuse foo::{\n Long, List, Of, Type, Imports,\n some_macro, imports,\n};\n```\n\n
\n\n**Order imports in order of decreasing \"distance\" to the current module: `std`,\n`core`, and `alloc`, external crates, then current crate. Prefer using `crate`\nrelative imports to `super`. Separate each category with one blank line.**\n\n\n\n \n \n \n \n\n\n \n \n\n\n\n
✅ YesNo 🚫
\n\n```rust\nuse std::{foo, bar};\nuse alloc::{bar, baz};\n\nuse either::Either;\nuse futures::{SomeItem, OtherItem};\n\nuse crate::{item1, item2};\nuse crate::module::item3;\nuse crate::module2::item4;\n```\n\n\n\n```rust\nuse crate::{item1, item2};\nuse std::{foo, bar};\nuse either::Either;\nuse alloc::{bar, baz};\nuse futures::{SomeItem, OtherItem};\n\nuse super::{item3, item4};\nuse super::item4;\n```\n\n
\n\n## Commit Message Guidelines\n[Commit Message Guidelines]: #commit-message-guidelines\n\nGit commit messages should start with a single-line _header_ of at most 50\ncharacters followed by a body with any number of descriptive paragraphs, with\nlines not to exceed 72 characters, and a footer.\n\nThe **header** must be an imperative statement that precisely describes the\nprimary change made by the commit. The goal is to give the reader a good\nunderstanding of what the commit does via only the header. It should not require\ncontext to understand. It should not include references to git commits or\nissues. Avoid using Markdown in the header if possible.\n\nTypically, the first word in the header will be one of the following:\n\n * **Fix** - to fix a functional or doc bug\n - Example: `Fix 'TcpListener': allow 'udp://' prefix.`\n * **Improve** - for minor feature or doc improvements\n - Example: `Improve 'FromParam' derive error messages.`\n * **Introduce** - for major feature introductions\n - Example: `Introduce WebSocket support.`\n * **Add**, **Remove** - for changes\n - Example: `Add 'Foo::new()' constructor.`\n - Example: `Remove 'Foo::new()'; add 'Foo::build()'.`\n * **Update** - for crate updates\n - Example: `Update 'base64' to 0.12.`\n * **Impl** or **Implement** - for trait implementations\n - Example: `Implement 'FromForm' for 'ThisNewType'.`\n\nNote how generic words like \"change\" are avoided, and how the headers are\nspecific about the changes they made. You need not limit yourself to this\nvocabulary. When in doubt, consult the `git log` for examples.\n\n| **✅ Yes** | **No 🚫** |\n|--------------------------------------------------|--------------------------------------------|\n| Fix 'FromForm' derive docs typo: 'yis' -> 'yes'. | ~~Change word in docs~~ |\n| Default 'MsgPack' to named variant. | ~~Change default to more likely variant.~~ |\n| Fix 'Compact' advice in 'MsgPack' docs. | ~~Update docs to make sense~~ |\n| Improve 'Sentinel' docs: explain 'Sentry'. | ~~Add missing doc details.~~ |\n| Fix CI: pin macOS CI 'mysql-client' to '8.4'. | ~~Fix CI~~ |\n| Fix link to 'rocket::build()' in config guide. | ~~Fix wrong URL in guide (configuration~~) |\n\nThe **body** should describe what the commit does. For example, if the commit\nintroduces a new feature it should describe what the feature enables and how it\nenables it. A body may be unnecessary if the header sufficiently describes the\ncommit. Avoid referencing issues in the body as well: we'll do that in the\nfooter. If you reference a commit, reference it by shorthash only. Feel free to\nuse markdown including lists and code.\n\nFinally, the **footer** is where references to issues should be made. See the\nGitHub's [linked issues] documentation.\n\n[linked issues]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue\n[Rust Style Guide]: https://doc.rust-lang.org/nightly/style-guide/\n[issue]: https://github.com/rwf2/Rocket/issues\n[pull request]: https://github.com/rwf2/Rocket/pulls\n[test.sh]: scripts/test.sh\n[mk-docs.sh]: scripts/mk-docs.sh\n[`trybuild`]: https://docs.rs/trybuild\n[sponsor the project]: https://github.com/sponsors/rwf2\n[docs/guide]: docs/guide\n\n## Licensing\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in Rocket by you shall be dual licensed under the MIT License and\nApache License, Version 2.0, without any additional terms or conditions.\n\nThe Rocket website docs are licensed under [separate terms](docs/LICENSE). Any\ncontribution intentionally submitted for inclusion in the Rocket website docs by\nyou shall be licensed under those terms.\n" }, { "path": "Cargo.toml", "content": "[workspace]\nresolver = \"2\"\nmembers = [\n \"core/lib/\",\n \"core/codegen/\",\n \"core/http/\",\n \"contrib/db_pools/codegen/\",\n \"contrib/db_pools/lib/\",\n \"contrib/sync_db_pools/codegen/\",\n \"contrib/sync_db_pools/lib/\",\n \"contrib/dyn_templates/\",\n \"contrib/ws/\",\n \"docs/tests\",\n]\n\n[workspace.lints.rust]\nunexpected_cfgs = { level = \"warn\", check-cfg = ['cfg(nightly)'] }\nrust_2018_idioms = \"warn\"\nasync_fn_in_trait = \"allow\"\nrefining_impl_trait = \"allow\"\n# unreachable_pub = \"warn\"\n# single_use_lifetimes = \"warn\"\n# missing_docs = \"warn\"\n\n[workspace.lints.clippy]\ntype_complexity = \"allow\"\nmodule_inception = \"allow\"\nmultiple_bound_locations = \"allow\"\nmanual_range_contains = \"allow\"\n" }, { "path": "LICENSE-APACHE", "content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright 2016 Sergio Benitez\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n\thttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "LICENSE-MIT", "content": "The MIT License (MIT)\nCopyright (c) 2016 Sergio Benitez\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies 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, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n" }, { "path": "README.md", "content": "# Rocket\n\n[![Build Status](https://github.com/rwf2/Rocket/workflows/CI/badge.svg)](https://github.com/rwf2/Rocket/actions)\n[![Rocket Homepage](https://img.shields.io/badge/web-rocket.rs-red.svg?style=flat&label=https&colorB=d33847)](https://rocket.rs)\n[![Current Crates.io Version](https://img.shields.io/crates/v/rocket.svg)](https://crates.io/crates/rocket)\n[![Matrix: #rocket:mozilla.org](https://img.shields.io/badge/style-%23rocket:mozilla.org-blue.svg?style=flat&label=[m])](https://chat.mozilla.org/#/room/#rocket:mozilla.org)\n\nRocket is an async web framework for Rust with a focus on usability, security,\nextensibility, and speed.\n\n```rust\n#[macro_use] extern crate rocket;\n\n#[get(\"//\")]\nfn hello(name: &str, age: u8) -> String {\n format!(\"Hello, {} year old named {}!\", age, name)\n}\n\n#[launch]\nfn rocket() -> _ {\n rocket::build().mount(\"/hello\", routes![hello])\n}\n```\n\nVisiting `localhost:8000/hello/John/58`, for example, will trigger the `hello`\nroute resulting in the string `Hello, 58 year old named John!` being sent to the\nbrowser. If an `` string was passed in that can't be parsed as a `u8`, the\nroute won't get called, resulting in a 404 error.\n\n## Documentation\n\nRocket is extensively documented:\n\n * [Overview]: A brief look at what makes Rocket special.\n * [Quickstart]: How to get started as quickly as possible.\n * [Getting Started]: How to start your first Rocket project.\n * [Guide]: A detailed guide and reference to Rocket.\n * [API Documentation]: The \"rustdocs\".\n\n[Quickstart]: https://rocket.rs/guide/quickstart\n[Getting Started]: https://rocket.rs/guide/getting-started\n[Overview]: https://rocket.rs/overview/\n[Guide]: https://rocket.rs/guide/\n[API Documentation]: https://api.rocket.rs\n\nDocumentation for the `master` branch is available at https://rocket.rs/master\nand https://api.rocket.rs/master.\n\nDocumentation for major release version `${x}` is available at\n`https://[api.]rocket.rs/v${x}`. For example, the v0.4 docs are available at\nhttps://rocket.rs/v0.4 and https://api.rocket.rs/v0.4.\n\nFinally, API docs for active git branches are available at\n`https://api.rocket.rs/${branch}`. For example, API docs for the `master` branch\nare available at https://api.rocket.rs/master. Branch rustdocs are built and\ndeployed on every commit.\n\n## Examples\n\nThe [examples](examples#readme) directory contains complete crates that showcase\nRocket's features and usage. Each example can be compiled and run with Cargo.\nFor instance, the following sequence of commands builds and runs the `hello`\nexample:\n\n```sh\ncd examples/hello\ncargo run\n```\n\n## Getting Help\n\nIf you find yourself needing help outside of the documentation, you may:\n\n * Ask questions via [GitHub discussions questions].\n * Chat with us at [`#rocket:mozilla.org`] on Matrix (join [via Element]).\n\n[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org\n[via Element]: https://chat.mozilla.org/#/room/#rocket:mozilla.org\n[GitHub discussions questions]: https://github.com/rwf2/Rocket/discussions/categories/questions\n\n## Contributing\n\nContributions are absolutely, positively welcomed and encouraged! If you're\ninterested in contributing code, please first read [CONTRIBUTING] for complete\nguidelines. Additionally, you could:\n\n 1. Submit a feature request or bug report as an [issue].\n 2. Ask for improved documentation as an [issue].\n 3. Comment on [issues that require feedback].\n 4. Answers questions in [GitHub discussions questions].\n 5. Share a project in [GitHub discussions show & tell].\n\n[issue]: https://github.com/rwf2/Rocket/issues\n[issues that require feedback]: https://github.com/rwf2/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22\n[pull requests]: https://github.com/rwf2/Rocket/pulls\n[CONTRIBUTING]: CONTRIBUTING.md\n[GitHub discussions show & tell]: https://github.com/rwf2/Rocket/discussions/categories/show-tell\n\n## License\n\nRocket is licensed under either of the following, at your option:\n\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)\n * MIT License ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in Rocket by you shall be dual licensed under the MIT License and\nApache License, Version 2.0, without any additional terms or conditions.\n\nThe Rocket website docs are licensed under [separate terms](docs/LICENSE). Any\ncontribution intentionally submitted for inclusion in the Rocket website docs by\nyou shall be licensed under those terms.\n" }, { "path": "benchmarks/Cargo.toml", "content": "[package]\nname = \"rocket-benchmarks\"\nversion = \"0.0.0\"\nedition = \"2021\"\npublish = false\n\n[workspace]\n\n[[bench]]\nname = \"main\"\npath = \"src/bench.rs\"\nharness = false\n\n[dev-dependencies]\nrocket = { path = \"../core/lib/\" }\ncriterion = \"0.5.1\"\n" }, { "path": "benchmarks/src/bench.rs", "content": "mod routing;\n\ncriterion::criterion_main!(routing::routing);\n" }, { "path": "benchmarks/src/routing.rs", "content": "use criterion::{criterion_group, Criterion};\n\nuse rocket::{route, config, Request, Data, Route, Config};\nuse rocket::http::{Method, RawStr, ContentType, Accept, Status};\nuse rocket::local::blocking::{Client, LocalRequest};\n\nfn dummy_handler<'r>(req: &'r Request, _: Data<'r>) -> route::BoxFuture<'r> {\n route::Outcome::from(req, ()).pin()\n}\n\nfn parse_routes_table(table: &str) -> Vec {\n let mut routes = vec![];\n for line in table.split(\"\\n\").filter(|s| !s.is_empty()) {\n let mut components = line.split(\" \");\n let method: Method = components.next().expect(\"c\").parse().expect(\"method\");\n let uri: &str = components.next().unwrap();\n\n let (mut rank, mut name, mut format) = (None, None, None);\n for component in components {\n match component {\n c if c.starts_with('[') => rank = c.trim_matches(&['[', ']'][..]).parse().ok(),\n c if c.starts_with('(') => name = Some(c.trim_matches(&['(', ')'][..])),\n c => format = c.parse().ok(),\n }\n }\n\n let mut route = Route::new(method, uri, dummy_handler);\n if let Some(rank) = rank {\n route.rank = rank;\n }\n\n route.format = format;\n route.name = name.map(|s| s.to_string().into());\n routes.push(route);\n }\n\n routes\n}\n\nfn generate_matching_requests<'c>(client: &'c Client, routes: &[Route]) -> Vec> {\n fn staticify_segment(segment: &RawStr) -> &str {\n segment.as_str().trim_matches(&['<', '>', '.', '_'][..])\n }\n\n fn request_for_route<'c>(client: &'c Client, route: &Route) -> LocalRequest<'c> {\n let path = route.uri.path()\n .raw_segments()\n .map(staticify_segment)\n .collect::>()\n .join(\"/\");\n\n let query = route.uri.query()\n .map(|q| q.raw_segments())\n .into_iter()\n .flatten()\n .map(staticify_segment)\n .collect::>()\n .join(\"&\");\n\n let uri = format!(\"/{}?{}\", path, query);\n let mut req = client.req(route.method.unwrap(), uri);\n if let Some(ref format) = route.format {\n if let Some(true) = route.method.and_then(|m| m.allows_request_body()) {\n req.add_header(ContentType::from(format.clone()));\n } else {\n req.add_header(Accept::from(format.clone()));\n }\n }\n\n req\n }\n\n routes.iter()\n .map(|route| request_for_route(client, route))\n .collect()\n}\n\nfn client(routes: Vec) -> Client {\n let config = Config {\n profile: Config::RELEASE_PROFILE,\n log_level: None,\n cli_colors: config::CliColors::Never,\n shutdown: config::ShutdownConfig {\n ctrlc: false,\n #[cfg(unix)]\n signals: std::collections::hash_set::HashSet::new(),\n ..Default::default()\n },\n ..Default::default()\n };\n\n match Client::untracked(rocket::custom(config).mount(\"/\", routes)) {\n Ok(client) => client,\n Err(e) => {\n drop(e);\n panic!(\"bad launch\")\n }\n }\n}\n\npub fn bench_rust_lang_routes(c: &mut Criterion) {\n let table = include_str!(\"../static/rust-lang.routes\");\n let routes = parse_routes_table(table);\n let client = client(routes.clone());\n let requests = generate_matching_requests(&client, &routes);\n c.bench_function(\"rust-lang.routes\", |b| b.iter(|| {\n for request in requests.clone() {\n let response = request.dispatch();\n assert_eq!(response.status(), Status::Ok);\n }\n }));\n}\n\npub fn bench_bitwarden_routes(c: &mut Criterion) {\n let table = include_str!(\"../static/bitwarden_rs.routes\");\n let routes = parse_routes_table(table);\n let client = client(routes.clone());\n let requests = generate_matching_requests(&client, &routes);\n c.bench_function(\"bitwarden_rs.routes\", |b| b.iter(|| {\n for request in requests.clone() {\n let response = request.dispatch();\n assert_eq!(response.status(), Status::Ok);\n }\n }));\n}\n\ncriterion_group!(routing, bench_rust_lang_routes, bench_bitwarden_routes);\n" }, { "path": "benchmarks/static/bitwarden_rs.routes", "content": "GET /attachments// (attachments)\nGET /alive (alive)\nGET /bwrs_static/ (static_files)\nPOST /api/accounts/register (register)\nGET /api/accounts/profile (profile)\nPUT /api/accounts/profile (put_profile)\nPOST /api/accounts/profile (post_profile)\nGET /api/users//public-key (get_public_keys)\nPOST /api/accounts/keys (post_keys)\nPOST /api/accounts/password (post_password)\nPOST /api/accounts/kdf (post_kdf)\nPOST /api/accounts/key (post_rotatekey)\nPOST /api/accounts/security-stamp (post_sstamp)\nPOST /api/accounts/email-token (post_email_token)\nPOST /api/accounts/email (post_email)\nPOST /api/accounts/verify-email (post_verify_email)\nPOST /api/accounts/verify-email-token (post_verify_email_token)\nPOST /api/accounts/delete-recover (post_delete_recover)\nPOST /api/accounts/delete-recover-token (post_delete_recover_token)\nDELETE /api/accounts (delete_account)\nPOST /api/accounts/delete (post_delete_account)\nGET /api/accounts/revision-date (revision_date)\nPOST /api/accounts/password-hint (password_hint)\nPOST /api/accounts/prelogin (prelogin)\nPOST /api/accounts/verify-password (verify_password)\nGET /api/sync? (sync)\nGET /api/ciphers (get_ciphers)\nGET /api/ciphers/ (get_cipher)\nGET /api/ciphers//admin (get_cipher_admin)\nGET /api/ciphers//details (get_cipher_details)\nPOST /api/ciphers (post_ciphers)\nPUT /api/ciphers//admin (put_cipher_admin)\nPOST /api/ciphers/admin (post_ciphers_admin)\nPOST /api/ciphers/create (post_ciphers_create)\nPOST /api/ciphers/import (post_ciphers_import)\nPOST /api/ciphers//attachment multipart/form-data (post_attachment)\nPOST /api/ciphers//attachment-admin multipart/form-data (post_attachment_admin)\nPOST /api/ciphers//attachment//share multipart/form-data (post_attachment_share)\nPOST /api/ciphers//attachment//delete (delete_attachment_post)\nPOST /api/ciphers//attachment//delete-admin (delete_attachment_post_admin)\nDELETE /api/ciphers//attachment/ (delete_attachment)\nDELETE /api/ciphers//attachment//admin (delete_attachment_admin)\nPOST /api/ciphers//admin (post_cipher_admin)\nPOST /api/ciphers//share (post_cipher_share)\nPUT /api/ciphers//share (put_cipher_share)\nPUT /api/ciphers/share (put_cipher_share_selected)\nPOST /api/ciphers/ (post_cipher)\nPUT /api/ciphers/ (put_cipher)\nPOST /api/ciphers//delete (delete_cipher_post)\nPOST /api/ciphers//delete-admin (delete_cipher_post_admin)\nPUT /api/ciphers//delete (delete_cipher_put)\nPUT /api/ciphers//delete-admin (delete_cipher_put_admin)\nDELETE /api/ciphers/ (delete_cipher)\nDELETE /api/ciphers//admin (delete_cipher_admin)\nDELETE /api/ciphers (delete_cipher_selected)\nPOST /api/ciphers/delete (delete_cipher_selected_post)\nPUT /api/ciphers/delete (delete_cipher_selected_put)\nDELETE /api/ciphers/admin (delete_cipher_selected_admin)\nPOST /api/ciphers/delete-admin (delete_cipher_selected_post_admin)\nPUT /api/ciphers/delete-admin (delete_cipher_selected_put_admin)\nPUT /api/ciphers//restore (restore_cipher_put)\nPUT /api/ciphers//restore-admin (restore_cipher_put_admin)\nPUT /api/ciphers/restore (restore_cipher_selected)\nPOST /api/ciphers/purge? (delete_all)\nPOST /api/ciphers/move (move_cipher_selected)\nPUT /api/ciphers/move (move_cipher_selected_put)\nPUT /api/ciphers//collections (put_collections_update)\nPOST /api/ciphers//collections (post_collections_update)\nPOST /api/ciphers//collections-admin (post_collections_admin)\nPUT /api/ciphers//collections-admin (put_collections_admin)\nGET /api/folders (get_folders)\nGET /api/folders/ (get_folder)\nPOST /api/folders (post_folders)\nPOST /api/folders/ (post_folder)\nPUT /api/folders/ (put_folder)\nPOST /api/folders//delete (delete_folder_post)\nDELETE /api/folders/ (delete_folder)\nGET /api/organizations/ (get_organization)\nPOST /api/organizations (create_organization)\nDELETE /api/organizations/ (delete_organization)\nPOST /api/organizations//delete (post_delete_organization)\nPOST /api/organizations//leave (leave_organization)\nGET /api/collections (get_user_collections)\nGET /api/organizations//collections (get_org_collections)\nGET /api/organizations//collections//details (get_org_collection_detail)\nGET /api/organizations//collections//users (get_collection_users)\nPUT /api/organizations//collections//users (put_collection_users)\nPUT /api/organizations/ (put_organization)\nPOST /api/organizations/ (post_organization)\nPOST /api/organizations//collections (post_organization_collections)\nDELETE /api/organizations//collections//user/ (delete_organization_collection_user)\nPOST /api/organizations//collections//delete-user/ (post_organization_collection_delete_user)\nPOST /api/organizations//collections/ (post_organization_collection_update)\nPUT /api/organizations//collections/ (put_organization_collection_update)\nDELETE /api/organizations//collections/ (delete_organization_collection)\nPOST /api/organizations//collections//delete (post_organization_collection_delete)\nGET /api/ciphers/organization-details? (get_org_details)\nGET /api/organizations//users (get_org_users)\nPOST /api/organizations//users/invite (send_invite)\nPOST /api/organizations//users//reinvite (reinvite_user)\nPOST /api/organizations//users//confirm (confirm_invite)\nPOST /api/organizations/<_org_id>/users/<_org_user_id>/accept (accept_invite)\nGET /api/organizations//users/ (get_user)\nPOST /api/organizations//users/ [1] (edit_user)\nPUT /api/organizations//users/ (put_organization_user)\nDELETE /api/organizations//users/ (delete_user)\nPOST /api/organizations//users//delete (post_delete_user)\nPOST /api/ciphers/import-organization? (post_org_import)\nGET /api/organizations//policies (list_policies)\nGET /api/organizations//policies/token? (list_policies_token)\nGET /api/organizations//policies/ (get_policy)\nPUT /api/organizations//policies/ (put_policy)\nGET /api/organizations//tax (get_organization_tax)\nGET /api/plans (get_plans)\nGET /api/plans/sales-tax-rates (get_plans_tax_rates)\nPOST /api/organizations//import (import)\nGET /api/two-factor (get_twofactor)\nPOST /api/two-factor/get-recover (get_recover)\nPOST /api/two-factor/recover (recover)\nPOST /api/two-factor/disable (disable_twofactor)\nPUT /api/two-factor/disable (disable_twofactor_put)\nPOST /api/two-factor/get-authenticator (generate_authenticator)\nPOST /api/two-factor/authenticator (activate_authenticator)\nPUT /api/two-factor/authenticator (activate_authenticator_put)\nPOST /api/two-factor/get-duo (get_duo)\nPOST /api/two-factor/duo (activate_duo)\nPUT /api/two-factor/duo (activate_duo_put)\nPOST /api/two-factor/get-email (get_email)\nPOST /api/two-factor/send-email-login (send_email_login)\nPOST /api/two-factor/send-email (send_email)\nPUT /api/two-factor/email (email)\nPOST /api/two-factor/get-u2f (generate_u2f)\nPOST /api/two-factor/get-u2f-challenge (generate_u2f_challenge)\nPOST /api/two-factor/u2f (activate_u2f)\nPUT /api/two-factor/u2f (activate_u2f_put)\nDELETE /api/two-factor/u2f (delete_u2f)\nPOST /api/two-factor/get-yubikey (generate_yubikey)\nPOST /api/two-factor/yubikey (activate_yubikey)\nPUT /api/two-factor/yubikey (activate_yubikey_put)\nPOST /api/sends (post_send)\nPOST /api/sends/file multipart/form-data (post_send_file)\nPOST /api/sends/access/ (post_access)\nPOST /api/sends//access/file/ (post_access_file)\nPUT /api/sends/ (put_send)\nDELETE /api/sends/ (delete_send)\nPUT /api/sends//remove-password (put_remove_password)\nPUT /api/devices/identifier//clear-token (clear_device_token)\nPUT /api/devices/identifier//token (put_device_token)\nGET /api/settings/domains (get_eq_domains)\nPOST /api/settings/domains (post_eq_domains)\nPUT /api/settings/domains (put_eq_domains)\nGET /api/hibp/breach? (hibp_breach)\nGET /admin (admin_disabled)\nPOST /identity/connect/token (login)\nGET /icons//icon.png (icon)\nPOST /notifications/hub/negotiate (negotiate)\nGET /notifications/hub (websockets_err)\n" }, { "path": "benchmarks/static/rust-lang.routes", "content": "GET / (index)\nGET / (category)\nGET /governance (governance)\nGET /governance/
/ [2] (team)\nGET /production/users (production)\nGET /sponsors (sponsors)\nGET // [4] (subject)\nGET /static/ (files)\nGET /robots.txt (robots_txt)\nGET /logos/ (logos)\nGET /components/<_file..> (components)\nGET / [3] (index_locale)\nGET // [11] (category_locale)\nGET //governance [10] (governance_locale)\nGET //governance/
/ [12] (team_locale)\nGET //production/users [10] (production_locale)\nGET //sponsors [10] (sponsors_locale)\nGET /// [14] (subject_locale)\nGET //components/<_file..> [12] (components_locale)\nGET / [19] (redirect)\nGET /pdfs/ (redirect_pdfs)\nGET /en-US (redirect_bare_en_us)\nGET /<_locale> [20] (redirect_bare_locale)\nGET /en-US/ (redirect_en_us)\nGET /<_locale>/ [20] (redirect_locale)\n" }, { "path": "contrib/db_pools/README.md", "content": "# `db_pools` [![ci.svg]][ci] [![crates.io]][crate] [![docs.svg]][crate docs]\n\n[crates.io]: https://img.shields.io/crates/v/rocket_db_pools.svg\n[crate]: https://crates.io/crates/rocket_db_pools\n[docs.svg]: https://img.shields.io/badge/web-master-red.svg?style=flat&label=docs&colorB=d33847\n[crate docs]: https://api.rocket.rs/master/rocket_db_pools\n[ci.svg]: https://github.com/rwf2/Rocket/workflows/CI/badge.svg\n[ci]: https://github.com/rwf2/Rocket/actions\n\nAsynchronous database driver integration for Rocket. See the [crate docs] for\nfull usage details.\n\n## Usage\n\n1. Add `rocket_db_pools` as a dependency with one or more [database driver\n features] enabled:\n\n ```toml\n [dependencies.rocket_db_pools]\n version = \"0.1.0\"\n features = [\"sqlx_sqlite\"]\n ```\n\n2. Choose a name for your database, here `sqlite_logs`. [Configure] _at least_ a\n URL for the database:\n\n ```toml\n [default.databases.sqlite_logs]\n url = \"/path/to/database.sqlite\"\n ```\n\n3. [Derive `Database`] for a unit type (`Logs` here) which\n wraps the selected driver's [`Pool`] type and is decorated with\n `#[database(\"name\")]`. Attach `Type::init()` to your application's `Rocket`\n to initialize the database pool:\n\n ```rust\n use rocket_db_pools::{Database, Connection};\n\n #[derive(Database)]\n #[database(\"sqlite_logs\")]\n struct Logs(sqlx::SqlitePool);\n\n #[launch]\n fn rocket() -> _ {\n rocket::build().attach(Logs::init())\n }\n ```\n\n4. Use [`Connection`] as a request guard to retrieve an\n active database connection:\n\n ```rust\n #[get(\"/\")]\n async fn read(mut db: Connection, id: i64) -> Result {\n sqlx::query!(\"SELECT content FROM logs WHERE id = ?\", id)\n .fetch_one(&mut *db)\n .map_ok(|r| Log(r.content))\n .await\n }\n ```\n\n[database driver features]: https://api.rocket.rs/master/rocket_db_pools/index.html#supported-drivers\n[`Pool`]: https://api.rocket.rs/master/rocket_db_pools/index.html#supported-drivers\n[Configure]: https://api.rocket.rs/master/rocket_db_pools/index.html#configuration\n[Derive `Database`]: https://api.rocket.rs/master/rocket_db_pools/derive.Database.html\n[`Connection`]: https://api.rocket.rs/master/rocket_db_pools/struct.Connection.html\n" }, { "path": "contrib/db_pools/codegen/Cargo.toml", "content": "[package]\nname = \"rocket_db_pools_codegen\"\nversion = \"0.1.0\"\nauthors = [\"Sergio Benitez \", \"Jeb Rosen \"]\ndescription = \"Procedural macros for rocket_db_pools.\"\nrepository = \"https://github.com/rwf2/Rocket/tree/master/contrib/db_pools\"\nreadme = \"../README.md\"\nkeywords = [\"rocket\", \"framework\", \"database\", \"pools\"]\nlicense = \"MIT OR Apache-2.0\"\nedition = \"2021\"\nrust-version = \"1.75\"\n\n[lib]\nproc-macro = true\n\n[lints]\nworkspace = true\n\n[dependencies]\ndevise = \"0.4\"\nquote = \"1\"\n\n[dev-dependencies]\nrocket = { path = \"../../../core/lib\", default-features = false }\nrocket_db_pools = { path = \"../lib\", features = [\"deadpool_postgres\"] }\ntrybuild = \"1.0\"\nversion_check = \"0.9\"\n" }, { "path": "contrib/db_pools/codegen/src/database.rs", "content": "use proc_macro::TokenStream;\n\nuse devise::{DeriveGenerator, FromMeta, MapperBuild, Support, ValidatorBuild};\nuse devise::proc_macro2_diagnostics::SpanDiagnosticExt;\nuse devise::syn::{self, spanned::Spanned};\n\nconst ONE_DATABASE_ATTR: &str = \"missing `#[database(\\\"name\\\")]` attribute\";\nconst ONE_UNNAMED_FIELD: &str = \"struct must have exactly one unnamed field\";\n\n#[derive(Debug, FromMeta)]\nstruct DatabaseAttribute {\n #[meta(naked)]\n name: String,\n}\n\npub fn derive_database(input: TokenStream) -> TokenStream {\n DeriveGenerator::build_for(input, quote!(impl rocket_db_pools::Database))\n .support(Support::TupleStruct)\n .validator(ValidatorBuild::new()\n .struct_validate(|_, s| {\n if s.fields.len() == 1 {\n Ok(())\n } else {\n Err(s.span().error(ONE_UNNAMED_FIELD))\n }\n })\n )\n .outer_mapper(MapperBuild::new()\n .struct_map(|_, s| {\n let pool_type = match &s.fields {\n syn::Fields::Unnamed(f) => &f.unnamed[0].ty,\n _ => unreachable!(\"Support::TupleStruct\"),\n };\n\n let decorated_type = &s.ident;\n let db_ty = quote_spanned!(decorated_type.span() =>\n <#decorated_type as rocket_db_pools::Database>\n );\n\n quote_spanned! { decorated_type.span() =>\n impl From<#pool_type> for #decorated_type {\n fn from(pool: #pool_type) -> Self {\n Self(pool)\n }\n }\n\n impl std::ops::Deref for #decorated_type {\n type Target = #pool_type;\n\n fn deref(&self) -> &Self::Target {\n &self.0\n }\n }\n\n impl std::ops::DerefMut for #decorated_type {\n fn deref_mut(&mut self) -> &mut Self::Target {\n &mut self.0\n }\n }\n\n #[rocket::async_trait]\n impl<'r> rocket::request::FromRequest<'r> for &'r #decorated_type {\n type Error = ();\n\n async fn from_request(\n req: &'r rocket::request::Request<'_>\n ) -> rocket::request::Outcome {\n match #db_ty::fetch(req.rocket()) {\n Some(db) => rocket::outcome::Outcome::Success(db),\n None => rocket::outcome::Outcome::Error((\n rocket::http::Status::InternalServerError, ()))\n }\n }\n }\n\n impl rocket::Sentinel for &#decorated_type {\n fn abort(rocket: &rocket::Rocket) -> bool {\n #db_ty::fetch(rocket).is_none()\n }\n }\n }\n })\n )\n .outer_mapper(quote!(#[rocket::async_trait]))\n .inner_mapper(MapperBuild::new()\n .try_struct_map(|_, s| {\n let db_name = DatabaseAttribute::one_from_attrs(\"database\", &s.attrs)?\n .map(|attr| attr.name)\n .ok_or_else(|| s.span().error(ONE_DATABASE_ATTR))?;\n\n let fairing_name = format!(\"'{}' Database Pool\", db_name);\n\n let pool_type = match &s.fields {\n syn::Fields::Unnamed(f) => &f.unnamed[0].ty,\n _ => unreachable!(\"Support::TupleStruct\"),\n };\n\n Ok(quote_spanned! { pool_type.span() =>\n type Pool = #pool_type;\n\n const NAME: &'static str = #db_name;\n\n fn init() -> rocket_db_pools::Initializer {\n rocket_db_pools::Initializer::with_name(#fairing_name)\n }\n })\n })\n )\n .to_tokens()\n}\n" }, { "path": "contrib/db_pools/codegen/src/lib.rs", "content": "#![recursion_limit=\"256\"]\n#![warn(rust_2018_idioms)]\n\n//! # `rocket_db_pool` - Code Generation\n//!\n//! Implements the code generation portion of the `rocket_db_pool` crate. This\n//! is an implementation detail. This create should never be depended on\n//! directly.\n\n#[macro_use] extern crate quote;\n\nmod database;\n\n/// Automatic derive for the [`Database`] trait.\n///\n/// ```rust\n/// use rocket_db_pools::Database;\n/// # type PoolType = rocket_db_pools::deadpool_postgres::Pool;\n///\n/// #[derive(Database)]\n/// #[database(\"database_name\")]\n/// struct Db(PoolType);\n/// ```\n///\n/// The derive generates an implementation of [`Database`] as follows:\n///\n/// * [`Database::NAME`] is set to the value in the `#[database(\"name\")]`\n/// attribute.\n///\n/// This names the database, providing an anchor to configure the database via\n/// `Rocket.toml` or any other configuration source. Specifically, the\n/// configuration in `databases.name` is used to configure the driver.\n///\n/// * [`Database::Pool`] is set to the wrapped type: `PoolType` above. The type\n/// must implement [`Pool`].\n///\n/// To meet the required [`Database`] supertrait bounds, this derive also\n/// generates implementations for:\n///\n/// * `From`\n///\n/// * `Deref`\n///\n/// * `DerefMut`\n///\n/// * `FromRequest<'_> for &Db`\n///\n/// * `Sentinel for &Db`\n///\n/// The `Deref` impls enable accessing the database pool directly from\n/// references `&Db` or `&mut Db`. To force a dereference to the underlying\n/// type, use `&db.0` or `&**db` or their `&mut` variants.\n///\n/// [`Database`]: ../rocket_db_pools/trait.Database.html\n/// [`Database::NAME`]: ../rocket_db_pools/trait.Database.html#associatedconstant.NAME\n/// [`Database::Pool`]: ../rocket_db_pools/trait.Database.html#associatedtype.Pool\n/// [`Pool`]: ../rocket_db_pools/trait.Pool.html\n#[proc_macro_derive(Database, attributes(database))]\npub fn derive_database(input: proc_macro::TokenStream) -> proc_macro::TokenStream {\n crate::database::derive_database(input)\n}\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail/database-syntax.rs", "content": "use rocket_db_pools::{deadpool_postgres, Database};\n\n#[derive(Database)]\n#[database(123)]\nstruct A(deadpool_postgres::Pool);\n\n#[derive(Database)]\n#[database(\"some-name\", \"another\")]\nstruct B(deadpool_postgres::Pool);\n\n#[derive(Database)]\n#[database(\"some-name\", name = \"another\")]\nstruct C(deadpool_postgres::Pool);\n\n#[derive(Database)]\n#[database(\"foo\")]\nenum D { }\n\n#[derive(Database)]\nstruct E(deadpool_postgres::Pool);\n\n#[derive(Database)]\n#[database(\"foo\")]\nstruct F;\n\n#[derive(Database)]\n#[database(\"foo\")]\nstruct G(deadpool_postgres::Pool, deadpool_postgres::Pool);\n\n#[derive(Database)]\n#[database(\"foo\")]\nstruct H {\n foo: deadpool_postgres::Pool,\n}\n\nfn main() { }\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail/database-types.rs", "content": "#[macro_use] extern crate rocket_db_pools;\n\nstruct Unknown;\n\n#[derive(Database)]\n#[database(\"foo\")]\nstruct A(Unknown);\n\n#[derive(Database)]\n#[database(\"bar\")]\nstruct B(Vec);\n\nfn main() { }\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail-nightly/database-syntax.stderr", "content": "error: invalid value: expected string literal\n --> tests/ui-fail-nightly/database-syntax.rs:4:12\n |\n4 | #[database(123)]\n | ^^^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:3:10\n |\n3 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: expected key/value `key = value`\n --> tests/ui-fail-nightly/database-syntax.rs:8:25\n |\n8 | #[database(\"some-name\", \"another\")]\n | ^^^^^^^^^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:7:10\n |\n7 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: unexpected attribute parameter: `name`\n --> tests/ui-fail-nightly/database-syntax.rs:12:25\n |\n12 | #[database(\"some-name\", name = \"another\")]\n | ^^^^^^^^^^^^^^^^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:11:10\n |\n11 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: enums are not supported\n --> tests/ui-fail-nightly/database-syntax.rs:16:1\n |\n16 | / #[database(\"foo\")]\n17 | | enum D { }\n | |___________^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:15:10\n |\n15 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: missing `#[database(\"name\")]` attribute\n --> tests/ui-fail-nightly/database-syntax.rs:20:1\n |\n20 | struct E(deadpool_postgres::Pool);\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:19:10\n |\n19 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: struct must have exactly one unnamed field\n --> tests/ui-fail-nightly/database-syntax.rs:23:1\n |\n23 | / #[database(\"foo\")]\n24 | | struct F;\n | |_________^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:22:10\n |\n22 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: struct must have exactly one unnamed field\n --> tests/ui-fail-nightly/database-syntax.rs:27:1\n |\n27 | / #[database(\"foo\")]\n28 | | struct G(deadpool_postgres::Pool, deadpool_postgres::Pool);\n | |___________________________________________________________^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:26:10\n |\n26 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: named structs are not supported\n --> tests/ui-fail-nightly/database-syntax.rs:31:1\n |\n31 | / #[database(\"foo\")]\n32 | | struct H {\n33 | | foo: deadpool_postgres::Pool,\n34 | | }\n | |_^\n |\nnote: error occurred while deriving `Database`\n --> tests/ui-fail-nightly/database-syntax.rs:30:10\n |\n30 | #[derive(Database)]\n | ^^^^^^^^\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail-nightly/database-types.stderr", "content": "error[E0277]: the trait bound `Unknown: Pool` is not satisfied\n --> tests/ui-fail-nightly/database-types.rs:7:10\n |\n7 | struct A(Unknown);\n | ^^^^^^^ the trait `Pool` is not implemented for `Unknown`\n |\n = help: the trait `Pool` is implemented for `deadpool::managed::Pool`\nnote: required by a bound in `rocket_db_pools::Database::Pool`\n --> $WORKSPACE/contrib/db_pools/lib/src/database.rs\n |\n | type Pool: Pool;\n | ^^^^ required by this bound in `Database::Pool`\n\nerror[E0277]: the trait bound `Vec: Pool` is not satisfied\n --> tests/ui-fail-nightly/database-types.rs:11:10\n |\n11 | struct B(Vec);\n | ^^^^^^^^ the trait `Pool` is not implemented for `Vec`\n |\n = help: the trait `Pool` is implemented for `deadpool::managed::Pool`\nnote: required by a bound in `rocket_db_pools::Database::Pool`\n --> $WORKSPACE/contrib/db_pools/lib/src/database.rs\n |\n | type Pool: Pool;\n | ^^^^ required by this bound in `Database::Pool`\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail-stable/database-syntax.stderr", "content": "error: invalid value: expected string literal\n --> tests/ui-fail-stable/database-syntax.rs:4:12\n |\n4 | #[database(123)]\n | ^^^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:3:10\n |\n3 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: expected key/value `key = value`\n --> tests/ui-fail-stable/database-syntax.rs:8:25\n |\n8 | #[database(\"some-name\", \"another\")]\n | ^^^^^^^^^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:7:10\n |\n7 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: unexpected attribute parameter: `name`\n --> tests/ui-fail-stable/database-syntax.rs:12:25\n |\n12 | #[database(\"some-name\", name = \"another\")]\n | ^^^^^^^^^^^^^^^^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:11:10\n |\n11 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: enums are not supported\n --> tests/ui-fail-stable/database-syntax.rs:16:1\n |\n16 | / #[database(\"foo\")]\n17 | | enum D { }\n | |___________^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:15:10\n |\n15 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: missing `#[database(\"name\")]` attribute\n --> tests/ui-fail-stable/database-syntax.rs:20:1\n |\n20 | struct E(deadpool_postgres::Pool);\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:19:10\n |\n19 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: struct must have exactly one unnamed field\n --> tests/ui-fail-stable/database-syntax.rs:23:1\n |\n23 | / #[database(\"foo\")]\n24 | | struct F;\n | |_________^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:22:10\n |\n22 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: struct must have exactly one unnamed field\n --> tests/ui-fail-stable/database-syntax.rs:27:1\n |\n27 | / #[database(\"foo\")]\n28 | | struct G(deadpool_postgres::Pool, deadpool_postgres::Pool);\n | |___________________________________________________________^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:26:10\n |\n26 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n\nerror: named structs are not supported\n --> tests/ui-fail-stable/database-syntax.rs:31:1\n |\n31 | / #[database(\"foo\")]\n32 | | struct H {\n33 | | foo: deadpool_postgres::Pool,\n34 | | }\n | |_^\n\nerror: [note] error occurred while deriving `Database`\n --> tests/ui-fail-stable/database-syntax.rs:30:10\n |\n30 | #[derive(Database)]\n | ^^^^^^^^\n |\n = note: this error originates in the derive macro `Database` (in Nightly builds, run with -Z macro-backtrace for more info)\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail-stable/database-types.stderr", "content": "error[E0277]: the trait bound `Unknown: Pool` is not satisfied\n --> tests/ui-fail-stable/database-types.rs:7:10\n |\n7 | struct A(Unknown);\n | ^^^^^^^ the trait `Pool` is not implemented for `Unknown`\n |\n = help: the trait `Pool` is implemented for `deadpool::managed::Pool`\nnote: required by a bound in `rocket_db_pools::Database::Pool`\n --> $WORKSPACE/contrib/db_pools/lib/src/database.rs\n |\n | type Pool: Pool;\n | ^^^^ required by this bound in `Database::Pool`\n\nerror[E0277]: the trait bound `Vec: Pool` is not satisfied\n --> tests/ui-fail-stable/database-types.rs:11:10\n |\n11 | struct B(Vec);\n | ^^^^^^^^ the trait `Pool` is not implemented for `Vec`\n |\n = help: the trait `Pool` is implemented for `deadpool::managed::Pool`\nnote: required by a bound in `rocket_db_pools::Database::Pool`\n --> $WORKSPACE/contrib/db_pools/lib/src/database.rs\n |\n | type Pool: Pool;\n | ^^^^ required by this bound in `Database::Pool`\n" }, { "path": "contrib/db_pools/codegen/tests/ui-fail.rs", "content": "#[test]\n#[ignore]\nfn ui() {\n let path = match version_check::is_feature_flaggable() {\n Some(true) => \"ui-fail-nightly\",\n _ => \"ui-fail-stable\"\n };\n\n let t = trybuild::TestCases::new();\n t.compile_fail(format!(\"tests/{}/*.rs\", path));\n}\n" }, { "path": "contrib/db_pools/lib/Cargo.toml", "content": "[package]\nname = \"rocket_db_pools\"\nversion = \"0.1.0\"\nauthors = [\"Sergio Benitez \", \"Jeb Rosen \"]\ndescription = \"Rocket async database pooling support\"\nrepository = \"https://github.com/rwf2/Rocket/tree/master/contrib/db_pools\"\nreadme = \"../README.md\"\nkeywords = [\"rocket\", \"framework\", \"database\", \"pools\"]\nlicense = \"MIT OR Apache-2.0\"\nedition = \"2021\"\nrust-version = \"1.75\"\n\n[package.metadata.docs.rs]\nall-features = true\n\n[lints]\nworkspace = true\n\n[features]\n# deadpool features\ndeadpool_postgres = [\"deadpool-postgres\", \"deadpool\"]\ndeadpool_redis = [\"deadpool-redis\", \"deadpool\"]\n# sqlx features\nsqlx_mysql = [\"sqlx\", \"sqlx/mysql\", \"log\"]\nsqlx_postgres = [\"sqlx\", \"sqlx/postgres\", \"log\"]\nsqlx_sqlite = [\"sqlx\", \"sqlx/sqlite\", \"log\"]\nsqlx_macros = [\"sqlx/macros\"]\n# diesel features\ndiesel_postgres = [\"diesel-async/postgres\", \"diesel-async/deadpool\", \"deadpool\", \"diesel\"]\ndiesel_mysql = [\"diesel-async/mysql\", \"diesel-async/deadpool\", \"deadpool\", \"diesel\"]\n# implicit features: mongodb\n\n[dependencies.rocket]\npath = \"../../../core/lib\"\nversion = \"0.6.0-dev\"\ndefault-features = false\n\n[dependencies.rocket_db_pools_codegen]\npath = \"../codegen\"\nversion = \"0.1.0\"\n\n[dependencies.deadpool]\nversion = \"0.12.1\"\ndefault-features = false\nfeatures = [\"rt_tokio_1\", \"managed\"]\noptional = true\n\n[dependencies.deadpool-postgres]\nversion = \"0.14\"\ndefault-features = false\nfeatures = [\"rt_tokio_1\"]\noptional = true\n\n[dependencies.deadpool-redis]\nversion = \"0.16\"\ndefault-features = false\nfeatures = [\"rt_tokio_1\"]\noptional = true\n\n[dependencies.mongodb]\nversion = \"3\"\ndefault-features = false\nfeatures = [\"compat-3-0-0\", \"rustls-tls\"]\noptional = true\n\n[dependencies.diesel-async]\nversion = \"0.6.0\"\ndefault-features = false\nfeatures = [\"async-connection-wrapper\"]\noptional = true\n\n[dependencies.diesel]\nversion = \"2.1\"\ndefault-features = false\noptional = true\n\n[dependencies.sqlx]\nversion = \"0.8\"\ndefault-features = false\nfeatures = [\"runtime-tokio-rustls\"]\noptional = true\n\n[dependencies.log]\nversion = \"0.4\"\ndefault-features = false\noptional = true\n\n[dev-dependencies.rocket]\npath = \"../../../core/lib\"\ndefault-features = false\nfeatures = [\"json\"]\n\n[build-dependencies]\nversion_check = \"0.9\"\n" }, { "path": "contrib/db_pools/lib/src/config.rs", "content": "use rocket::serde::{Deserialize, Serialize};\n\n/// Base configuration for all database drivers.\n///\n/// A dictionary matching this structure is extracted from the active\n/// [`Figment`](crate::figment::Figment), scoped to `databases.name`, where\n/// `name` is the name of the database, by the\n/// [`Initializer`](crate::Initializer) fairing on ignition and used to\n/// configure the relevant database and database pool.\n///\n/// With the default provider, these parameters are typically configured in a\n/// `Rocket.toml` file:\n///\n/// ```toml\n/// [default.databases.db_name]\n/// url = \"/path/to/db.sqlite\"\n///\n/// # Only `url` is required. These have sane defaults and are optional.\n/// min_connections = 64\n/// max_connections = 1024\n/// connect_timeout = 5\n/// idle_timeout = 120\n///\n/// # This option is only supported by the `sqlx_sqlite` driver.\n/// extensions = [\"memvfs\", \"rot13\"]\n/// ```\n///\n/// Alternatively, a custom provider can be used. For example, a custom `Figment`\n/// with a global `databases.name` configuration:\n///\n/// ```rust\n/// # use rocket::launch;\n/// #[launch]\n/// fn rocket() -> _ {\n/// let figment = rocket::Config::figment()\n/// .merge((\"databases.name\", rocket_db_pools::Config {\n/// url: \"db:specific@config&url\".into(),\n/// min_connections: None,\n/// max_connections: 1024,\n/// connect_timeout: 3,\n/// idle_timeout: None,\n/// extensions: None,\n/// }));\n///\n/// rocket::custom(figment)\n/// }\n/// ```\n///\n/// For general information on configuration in Rocket, see [`rocket::config`].\n/// For higher-level details on configuring a database, see the [crate-level\n/// docs](crate#configuration).\n// NOTE: Defaults provided by the figment created in the `Initializer` fairing.\n#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]\n#[serde(crate = \"rocket::serde\")]\npub struct Config {\n /// Database-specific connection and configuration URL.\n ///\n /// The format of the URL is database specific; consult your database's\n /// documentation.\n pub url: String,\n /// Minimum number of connections to maintain in the pool.\n ///\n /// **Note:** `deadpool` drivers do not support and thus ignore this value.\n ///\n /// _Default:_ `None`.\n pub min_connections: Option,\n /// Maximum number of connections to maintain in the pool.\n ///\n /// _Default:_ `workers * 4`.\n pub max_connections: usize,\n /// Number of seconds to wait for a connection before timing out.\n ///\n /// If the timeout elapses before a connection can be made or retrieved from\n /// a pool, an error is returned.\n ///\n /// _Default:_ `5`.\n pub connect_timeout: u64,\n /// Maximum number of seconds to keep a connection alive for.\n ///\n /// After a connection is established, it is maintained in a pool for\n /// efficient connection retrieval. When an `idle_timeout` is set, that\n /// connection will be closed after the timeout elapses. If an\n /// `idle_timeout` is not specified, the behavior is driver specific but\n /// typically defaults to keeping a connection active indefinitely.\n ///\n /// _Default:_ `None`.\n pub idle_timeout: Option,\n /// A list of database extensions to load at run-time.\n ///\n /// **Note:** Only the `sqlx_sqlite` driver supports this option (for SQLite\n /// extensions) at this time. All other drivers ignore this option.\n ///\n /// _Default:_ `None`.\n pub extensions: Option>,\n}\n\nimpl Default for Config {\n fn default() -> Self {\n Self {\n url: Default::default(),\n min_connections: Default::default(),\n max_connections: rocket::Config::default().workers * 4,\n connect_timeout: 5,\n idle_timeout: Default::default(),\n extensions: Default::default(),\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::Config;\n\n #[test]\n fn default_values_sane() {\n let config = Config::default();\n assert_ne!(config.max_connections, 0);\n assert_eq!(config.connect_timeout, 5);\n }\n}\n" }, { "path": "contrib/db_pools/lib/src/database.rs", "content": "use std::marker::PhantomData;\nuse std::ops::{Deref, DerefMut};\n\nuse rocket::{error, Build, Ignite, Phase, Rocket, Sentinel, Orbit};\nuse rocket::fairing::{self, Fairing, Info, Kind};\nuse rocket::request::{FromRequest, Outcome, Request};\nuse rocket::figment::providers::Serialized;\nuse rocket::http::Status;\n\nuse crate::Pool;\n\n/// Derivable trait which ties a database [`Pool`] with a configuration name.\n///\n/// This trait should rarely, if ever, be implemented manually. Instead, it\n/// should be derived:\n///\n/// ```rust\n/// # #[cfg(feature = \"deadpool_redis\")] mod _inner {\n/// # use rocket::launch;\n/// use rocket_db_pools::{deadpool_redis, Database};\n///\n/// #[derive(Database)]\n/// #[database(\"memdb\")]\n/// struct Db(deadpool_redis::Pool);\n///\n/// #[launch]\n/// fn rocket() -> _ {\n/// rocket::build().attach(Db::init())\n/// }\n/// # }\n/// ```\n///\n/// See the [`Database` derive](derive@crate::Database) for details.\npub trait Database: From + DerefMut + Send + Sync + 'static {\n /// The [`Pool`] type of connections to this database.\n ///\n /// When `Database` is derived, this takes the value of the `Inner` type in\n /// `struct Db(Inner)`.\n type Pool: Pool;\n\n /// The configuration name for this database.\n ///\n /// When `Database` is derived, this takes the value `\"name\"` in the\n /// `#[database(\"name\")]` attribute.\n const NAME: &'static str;\n\n /// Returns a fairing that initializes the database and its connection pool.\n ///\n /// # Example\n ///\n /// ```rust\n /// # #[cfg(feature = \"deadpool_postgres\")] mod _inner {\n /// # use rocket::launch;\n /// use rocket_db_pools::{deadpool_postgres, Database};\n ///\n /// #[derive(Database)]\n /// #[database(\"pg_db\")]\n /// struct Db(deadpool_postgres::Pool);\n ///\n /// #[launch]\n /// fn rocket() -> _ {\n /// rocket::build().attach(Db::init())\n /// }\n /// # }\n /// ```\n fn init() -> Initializer {\n Initializer::new()\n }\n\n /// Returns a reference to the initialized database in `rocket`. The\n /// initializer fairing returned by `init()` must have already executed for\n /// `Option` to be `Some`. This is guaranteed to be the case if the fairing\n /// is attached and either:\n ///\n /// * Rocket is in the [`Orbit`](rocket::Orbit) phase. That is, the\n /// application is running. This is always the case in request guards\n /// and liftoff fairings,\n /// * _or_ Rocket is in the [`Build`](rocket::Build) or\n /// [`Ignite`](rocket::Ignite) phase and the `Initializer` fairing has\n /// already been run. This is the case in all fairing callbacks\n /// corresponding to fairings attached _after_ the `Initializer`\n /// fairing.\n ///\n /// # Example\n ///\n /// Run database migrations in an ignite fairing. It is imperative that the\n /// migration fairing be registered _after_ the `init()` fairing.\n ///\n /// ```rust\n /// # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n /// # use rocket::launch;\n /// use rocket::{Rocket, Build};\n /// use rocket::fairing::{self, AdHoc};\n ///\n /// use rocket_db_pools::{sqlx, Database};\n ///\n /// #[derive(Database)]\n /// #[database(\"sqlite_db\")]\n /// struct Db(sqlx::SqlitePool);\n ///\n /// async fn run_migrations(rocket: Rocket) -> fairing::Result {\n /// if let Some(db) = Db::fetch(&rocket) {\n /// // run migrations using `db`. get the inner type with &db.0.\n /// Ok(rocket)\n /// } else {\n /// Err(rocket)\n /// }\n /// }\n ///\n /// #[launch]\n /// fn rocket() -> _ {\n /// rocket::build()\n /// .attach(Db::init())\n /// .attach(AdHoc::try_on_ignite(\"DB Migrations\", run_migrations))\n /// }\n /// # }\n /// ```\n fn fetch(rocket: &Rocket

) -> Option<&Self> {\n if let Some(db) = rocket.state() {\n return Some(db);\n }\n\n let conn = std::any::type_name::();\n error!(\"`{conn}::init()` is not attached\\n\\\n the fairing must be attached to use `{conn}` in routes.\");\n\n None\n }\n}\n\n/// A [`Fairing`] which initializes a [`Database`] and its connection pool.\n///\n/// A value of this type can be created for any type `D` that implements\n/// [`Database`] via the [`Database::init()`] method on the type. Normally, a\n/// value of this type _never_ needs to be constructed directly. This\n/// documentation exists purely as a reference.\n///\n/// This fairing initializes a database pool. Specifically, it:\n///\n/// 1. Reads the configuration at `database.db_name`, where `db_name` is\n/// [`Database::NAME`].\n///\n/// 2. Sets [`Config`](crate::Config) defaults on the configuration figment.\n///\n/// 3. Calls [`Pool::init()`].\n///\n/// 4. Stores the database instance in managed storage, retrievable via\n/// [`Database::fetch()`].\n///\n/// The name of the fairing itself is `Initializer`, with `D` replaced with\n/// the type name `D` unless a name is explicitly provided via\n/// [`Self::with_name()`].\npub struct Initializer(Option<&'static str>, PhantomData D>);\n\n/// A request guard which retrieves a single connection to a [`Database`].\n///\n/// For a database type of `Db`, a request guard of `Connection` retrieves a\n/// single connection to `Db`.\n///\n/// The request guard succeeds if the database was initialized by the\n/// [`Initializer`] fairing and a connection is available within\n/// [`connect_timeout`](crate::Config::connect_timeout) seconds.\n/// * If the `Initializer` fairing was _not_ attached, the guard _fails_ with\n/// status `InternalServerError`. A [`Sentinel`] guards this condition, and so\n/// this type of error is unlikely to occur. A `None` error is returned.\n/// * If a connection is not available within `connect_timeout` seconds or\n/// another error occurs, the guard _fails_ with status `ServiceUnavailable`\n/// and the error is returned in `Some`.\n///\n/// ## Deref\n///\n/// A type of `Connection` dereferences, mutably and immutably, to the\n/// native database connection type. The [driver table](crate#supported-drivers)\n/// lists the concrete native `Deref` types.\n///\n/// # Example\n///\n/// ```rust\n/// # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n/// # use rocket::get;\n/// # type Pool = rocket_db_pools::sqlx::SqlitePool;\n/// use rocket_db_pools::{Database, Connection};\n///\n/// #[derive(Database)]\n/// #[database(\"db\")]\n/// struct Db(Pool);\n///\n/// #[get(\"/\")]\n/// async fn db_op(db: Connection) {\n/// // use `&*db` to get an immutable borrow to the native connection type\n/// // use `&mut *db` to get a mutable borrow to the native connection type\n/// }\n/// # }\n/// ```\npub struct Connection(::Connection);\n\nimpl Initializer {\n /// Returns a database initializer fairing for `D`.\n ///\n /// This method should never need to be called manually. See the [crate\n /// docs](crate) for usage information.\n pub fn new() -> Self {\n Self(None, std::marker::PhantomData)\n }\n\n /// Returns a database initializer fairing for `D` with name `name`.\n ///\n /// This method should never need to be called manually. See the [crate\n /// docs](crate) for usage information.\n pub fn with_name(name: &'static str) -> Self {\n Self(Some(name), std::marker::PhantomData)\n }\n}\n\nimpl Connection {\n /// Returns the internal connection value. See the [`Connection` Deref\n /// column](crate#supported-drivers) for the expected type of this value.\n ///\n /// Note that `Connection` derefs to the internal connection type, so\n /// using this method is likely unnecessary. See [deref](Connection#deref)\n /// for examples.\n ///\n /// # Example\n ///\n /// ```rust\n /// # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n /// # use rocket::get;\n /// # type Pool = rocket_db_pools::sqlx::SqlitePool;\n /// use rocket_db_pools::{Database, Connection};\n ///\n /// #[derive(Database)]\n /// #[database(\"db\")]\n /// struct Db(Pool);\n ///\n /// #[get(\"/\")]\n /// async fn db_op(db: Connection) {\n /// let inner = db.into_inner();\n /// }\n /// # }\n /// ```\n pub fn into_inner(self) -> ::Connection {\n self.0\n }\n}\n\n#[rocket::async_trait]\nimpl Fairing for Initializer {\n fn info(&self) -> Info {\n Info {\n name: self.0.unwrap_or(std::any::type_name::()),\n kind: Kind::Ignite | Kind::Shutdown,\n }\n }\n\n async fn on_ignite(&self, rocket: Rocket) -> fairing::Result {\n let workers: usize = rocket.figment()\n .extract_inner(rocket::Config::WORKERS)\n .unwrap_or_else(|_| rocket::Config::default().workers);\n\n let figment = rocket.figment()\n .focus(&format!(\"databases.{}\", D::NAME))\n .join(Serialized::default(\"max_connections\", workers * 4))\n .join(Serialized::default(\"connect_timeout\", 5));\n\n match ::init(&figment).await {\n Ok(pool) => Ok(rocket.manage(D::from(pool))),\n Err(e) => {\n error!(\"database initialization failed: {e}\");\n Err(rocket)\n }\n }\n }\n\n async fn on_shutdown(&self, rocket: &Rocket) {\n if let Some(db) = D::fetch(rocket) {\n db.close().await;\n }\n }\n}\n\n#[rocket::async_trait]\nimpl<'r, D: Database> FromRequest<'r> for Connection {\n type Error = Option<::Error>;\n\n async fn from_request(req: &'r Request<'_>) -> Outcome {\n match D::fetch(req.rocket()) {\n Some(db) => match db.get().await {\n Ok(conn) => Outcome::Success(Connection(conn)),\n Err(e) => Outcome::Error((Status::ServiceUnavailable, Some(e))),\n },\n None => Outcome::Error((Status::InternalServerError, None)),\n }\n }\n}\n\nimpl Sentinel for Connection {\n fn abort(rocket: &Rocket) -> bool {\n D::fetch(rocket).is_none()\n }\n}\n\nimpl Deref for Connection {\n type Target = ::Connection;\n\n fn deref(&self) -> &Self::Target {\n &self.0\n }\n}\n\nimpl DerefMut for Connection {\n fn deref_mut(&mut self) -> &mut Self::Target {\n &mut self.0\n }\n}\n" }, { "path": "contrib/db_pools/lib/src/diesel.rs", "content": "//! Re-export of [`diesel`] with prelude types overridden with `async` variants\n//! from [`diesel_async`].\n//!\n//! # Usage\n//!\n//! To use `async` `diesel` support provided here, enable the following\n//! dependencies in your `Cargo.toml`:\n//!\n//! ```toml\n//! [dependencies]\n//! rocket = \"0.6.0-dev\"\n//! diesel = \"2\"\n//!\n//! [dependencies.rocket_db_pools]\n//! version = \"0.1.0\"\n//! features = [\"diesel_mysql\"]\n//! ```\n//!\n//! Then, import `rocket_db_pools::diesel::prelude::*` as well as the\n//! appropriate pool type and, optionally, [`QueryResult`]. To use macros or\n//! `diesel` functions, use `diesel::` directly. That is, _do not_ import\n//! `rocket_db_pools::diesel`. Doing so will, by design, cause import errors.\n//!\n//! # Example\n//!\n//! ```rust\n//! # #[macro_use] extern crate rocket;\n//! # #[cfg(feature = \"diesel_mysql\")] {\n//! use rocket_db_pools::{Database, Connection};\n//! use rocket_db_pools::diesel::{QueryResult, MysqlPool, prelude::*};\n//!\n//! #[derive(Database)]\n//! #[database(\"diesel_mysql\")]\n//! struct Db(MysqlPool);\n//!\n//! #[derive(Queryable, Insertable)]\n//! #[diesel(table_name = posts)]\n//! struct Post {\n//! id: i64,\n//! title: String,\n//! published: bool,\n//! }\n//!\n//! diesel::table! {\n//! posts (id) {\n//! id -> BigInt,\n//! title -> Text,\n//! published -> Bool,\n//! }\n//! }\n//!\n//! #[get(\"/\")]\n//! async fn list(mut db: Connection) -> QueryResult {\n//! let post_ids: Vec = posts::table\n//! .select(posts::id)\n//! .load(&mut db)\n//! .await?;\n//!\n//! Ok(format!(\"{post_ids:?}\"))\n//! }\n//! # }\n//! ```\n\n/// The [`diesel`] prelude with `sync`-only traits replaced with their\n/// [`diesel_async`] variants.\npub mod prelude {\n #[doc(inline)]\n pub use diesel::prelude::*;\n\n #[doc(inline)]\n pub use diesel_async::{AsyncConnection, RunQueryDsl, SaveChangesDsl};\n}\n\n#[doc(hidden)]\npub use diesel::*;\n\n#[doc(hidden)]\npub use diesel_async::{RunQueryDsl, SaveChangesDsl, *};\n\n#[doc(hidden)]\n#[cfg(feature = \"diesel_postgres\")]\npub use diesel_async::pg;\n\n#[doc(inline)]\npub use diesel_async::pooled_connection::deadpool::Pool;\n\n#[doc(inline)]\npub use diesel_async::async_connection_wrapper::AsyncConnectionWrapper;\n\n#[doc(inline)]\n#[cfg(feature = \"diesel_mysql\")]\npub use diesel_async::AsyncMysqlConnection;\n\n#[doc(inline)]\n#[cfg(feature = \"diesel_postgres\")]\npub use diesel_async::AsyncPgConnection;\n\n/// Alias of a `Result` with an error type of [`Debug`] for a `diesel::Error`.\n///\n/// `QueryResult` is a [`Responder`](rocket::response::Responder) when `T` (the\n/// `Ok` value) is a `Responder`. By using this alias as a route handler's\n/// return type, the `?` operator can be applied to fallible `diesel` functions\n/// in the route handler while still providing a valid `Responder` return type.\n///\n/// See the [module level docs](self#example) for a usage example.\n///\n/// [`Debug`]: rocket::response::Debug\npub type QueryResult> = Result;\n\n/// Type alias for an `async` pool of MySQL connections for `async` [diesel].\n///\n/// ```rust\n/// # extern crate rocket;\n/// # #[cfg(feature = \"diesel_mysql\")] {\n/// # use rocket::get;\n/// use rocket_db_pools::{Database, Connection};\n/// use rocket_db_pools::diesel::{MysqlPool, prelude::*};\n///\n/// #[derive(Database)]\n/// #[database(\"my_mysql_db_name\")]\n/// struct Db(MysqlPool);\n///\n/// #[get(\"/\")]\n/// async fn use_db(mut db: Connection) {\n/// /* .. */\n/// }\n/// # }\n/// ```\n#[cfg(feature = \"diesel_mysql\")]\npub type MysqlPool = Pool;\n\n/// Type alias for an `async` pool of Postgres connections for `async` [diesel].\n///\n/// ```rust\n/// # extern crate rocket;\n/// # #[cfg(feature = \"diesel_postgres\")] {\n/// # use rocket::get;\n/// use rocket_db_pools::{Database, Connection};\n/// use rocket_db_pools::diesel::{PgPool, prelude::*};\n///\n/// #[derive(Database)]\n/// #[database(\"my_pg_db_name\")]\n/// struct Db(PgPool);\n///\n/// #[get(\"/\")]\n/// async fn use_db(mut db: Connection) {\n/// /* .. */\n/// }\n/// # }\n/// ```\n#[cfg(feature = \"diesel_postgres\")]\npub type PgPool = Pool;\n" }, { "path": "contrib/db_pools/lib/src/error.rs", "content": "use std::fmt;\n\n/// A general error type for use by [`Pool`](crate::Pool#implementing)\n/// implementors and returned by the [`Connection`](crate::Connection) request\n/// guard.\n#[derive(Debug)]\npub enum Error {\n /// An error that occurred during database/pool initialization.\n Init(A),\n\n /// An error that occurred while retrieving a connection from the pool.\n Get(B),\n\n /// A [`Figment`](crate::figment::Figment) configuration error.\n Config(crate::figment::Error),\n}\n\nimpl fmt::Display for Error {\n fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n match self {\n Error::Init(e) => write!(f, \"failed to initialize database: {}\", e),\n Error::Get(e) => write!(f, \"failed to get db connection: {}\", e),\n Error::Config(e) => write!(f, \"bad configuration: {}\", e),\n }\n }\n}\n\nimpl std::error::Error for Error\n where A: fmt::Debug + fmt::Display, B: fmt::Debug + fmt::Display {}\n\nimpl From for Error {\n fn from(e: crate::figment::Error) -> Self {\n Self::Config(e)\n }\n}\n" }, { "path": "contrib/db_pools/lib/src/lib.rs", "content": "//! Asynchronous database driver connection pooling integration for Rocket.\n//!\n//! # Quickstart\n//!\n//! 1. Add `rocket_db_pools` as a dependency with one or more [database driver\n//! features](#supported-drivers) enabled:\n//!\n//! ```toml\n//! [dependencies.rocket_db_pools]\n//! version = \"0.1.0\"\n//! features = [\"sqlx_sqlite\"]\n//! ```\n//!\n//! 2. Choose a name for your database, here `sqlite_logs`.\n//! [Configure](#configuration) _at least_ a URL for the database:\n//!\n//! ```toml\n//! [default.databases.sqlite_logs]\n//! url = \"/path/to/database.sqlite\"\n//! ```\n//!\n//! 3. [Derive](derive@Database) [`Database`] for a unit type (`Logs` here)\n//! which wraps the selected driver's [`Pool`] type (see [the driver\n//! table](#supported-drivers)) and is decorated with `#[database(\"name\")]`.\n//! Attach `Type::init()` to your application's `Rocket` to initialize the\n//! database pool:\n//!\n//! ```rust\n//! # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n//! # use rocket::launch;\n//! use rocket_db_pools::{sqlx, Database};\n//!\n//! #[derive(Database)]\n//! #[database(\"sqlite_logs\")]\n//! struct Logs(sqlx::SqlitePool);\n//!\n//! #[launch]\n//! fn rocket() -> _ {\n//! rocket::build().attach(Logs::init())\n//! }\n//! # }\n//! ```\n//!\n//! 4. Use [`Connection`](Connection) as a request guard to retrieve an\n//! active database connection, which dereferences to the native type in the\n//! [`Connection` deref](#supported-drivers) column.\n//!\n//! ```rust\n//! # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n//! # use rocket::{get, response::Responder};\n//! # use rocket_db_pools::{sqlx, Database};\n//! # #[derive(Database)]\n//! # #[database(\"sqlite_logs\")]\n//! # struct Logs(sqlx::SqlitePool);\n//! #\n//! # #[derive(Responder)]\n//! # struct Log(String);\n//! #\n//! use rocket_db_pools::Connection;\n//! use rocket_db_pools::sqlx::Row;\n//!\n//! #[get(\"/\")]\n//! async fn read(mut db: Connection, id: i64) -> Option {\n//! sqlx::query(\"SELECT content FROM logs WHERE id = ?\").bind(id)\n//! .fetch_one(&mut **db).await\n//! .and_then(|r| Ok(Log(r.try_get(0)?)))\n//! .ok()\n//! }\n//! # }\n//! ```\n//!\n//! Alternatively, use a reference to the database type as a request guard to\n//! retrieve the entire pool, but note that unlike retrieving a `Connection`,\n//! doing so does _not_ guarantee that a connection is available:\n//!\n//! ```rust\n//! # #[cfg(feature = \"sqlx_sqlite\")] mod _inner {\n//! # use rocket::{get, response::Responder};\n//! # use rocket_db_pools::{sqlx, Database};\n//! # #[derive(Database)]\n//! # #[database(\"sqlite_logs\")]\n//! # struct Logs(sqlx::SqlitePool);\n//! #\n//! # #[derive(Responder)]\n//! # struct Log(String);\n//! #\n//! use rocket_db_pools::sqlx::Row;\n//!\n//! #[get(\"/\")]\n//! async fn read(db: &Logs, id: i64) -> Option {\n//! sqlx::query(\"SELECT content FROM logs WHERE id = ?\").bind(id)\n//! .fetch_one(&db.0).await\n//! .and_then(|r| Ok(Log(r.try_get(0)?)))\n//! .ok()\n//! }\n//! # }\n//! ```\n//!\n//! # Supported Drivers\n//!\n//! At present, this crate supports _four_ drivers: [`deadpool`], [`sqlx`],\n//! [`mongodb`], and [`diesel`]. Each driver may support multiple databases.\n//! Drivers have a varying degree of support for graceful shutdown, affected by\n//! the `Type::init()` fairing on Rocket shutdown.\n//!\n//! ## `deadpool` (v0.12)\n//!\n//! | Database | Feature | [`Pool`] Type | [`Connection`] Deref |\n//! |----------|-----------------------------|-----------------------------|--------------------------------------|\n//! | Postgres | `deadpool_postgres` (v0.14) | [`deadpool_postgres::Pool`] | [`deadpool_postgres::ClientWrapper`] |\n//! | Redis | `deadpool_redis` (v0.16) | [`deadpool_redis::Pool`] | [`deadpool_redis::Connection`] |\n//!\n//! On shutdown, new connections are denied. Shutdown _does not_ wait for\n//! connections to be returned.\n//!\n//! ## `sqlx` (v0.7)\n//!\n//! | Database | Feature | [`Pool`] Type | [`Connection`] Deref |\n//! |----------|-----------------|----------------------|------------------------------------------|\n//! | Postgres | `sqlx_postgres` | [`sqlx::PgPool`] | [`sqlx::pool::PoolConnection`] |\n//! | MySQL | `sqlx_mysql` | [`sqlx::MySqlPool`] | [`sqlx::pool::PoolConnection`] |\n//! | SQLite | `sqlx_sqlite` | [`sqlx::SqlitePool`] | [`sqlx::pool::PoolConnection`] |\n//!\n//! [`sqlx::PgPool`]: https://docs.rs/sqlx/0.6/sqlx/type.PgPool.html\n//! [`sqlx::MySqlPool`]: https://docs.rs/sqlx/0.6/sqlx/type.MySqlPool.html\n//! [`sqlx::SqlitePool`]: https://docs.rs/sqlx/0.6/sqlx/type.SqlitePool.html\n//! [`sqlx::pool::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html\n//! [`sqlx::pool::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html\n//! [`sqlx::pool::PoolConnection`]: https://docs.rs/sqlx/0.6/sqlx/pool/struct.PoolConnection.html\n//!\n//! On shutdown, new connections are denied. Shutdown waits for connections to\n//! be returned.\n//!\n//! ## `mongodb` (v3)\n//!\n//! | Database | Feature | [`Pool`] Type and [`Connection`] Deref |\n//! |----------|-----------|----------------------------------------|\n//! | MongoDB | `mongodb` | [`mongodb::Client`] |\n//!\n//! Graceful shutdown is not supported.\n//!\n//! ## `diesel` (v2)\n//!\n//! | Database | Feature | [`Pool`] Type | [`Connection`] Deref |\n//! |----------|-------------------|-----------------------|----------------------------------|\n//! | Postgres | `diesel_postgres` | [`diesel::PgPool`] | [`diesel::AsyncPgConnection`] |\n//! | MySQL | `diesel_mysql` | [`diesel::MysqlPool`] | [`diesel::AsyncMysqlConnection`] | //!\n//!\n//! See [`diesel`] for usage details.\n//!\n//! On shutdown, new connections are denied. Shutdown _does not_ wait for\n//! connections to be returned.\n//!\n//! ## Enabling Additional Driver Features\n//!\n//! Only the minimal features for each driver crate are enabled by\n//! `rocket_db_pools`. To use additional driver functionality exposed via its\n//! crate's features, you'll need to depend on the crate directly with those\n//! features enabled in `Cargo.toml`:\n//!\n//! ```toml\n//! [dependencies.sqlx]\n//! version = \"0.7\"\n//! default-features = false\n//! features = [\"macros\", \"migrate\"]\n//!\n//! [dependencies.rocket_db_pools]\n//! version = \"0.1.0\"\n//! features = [\"sqlx_sqlite\"]\n//! ```\n//!\n//! # Configuration\n//!\n//! Configuration for a database named `db_name` is deserialized from a\n//! `databases.db_name` configuration parameter into a [`Config`] structure via\n//! Rocket's [configuration facilities](rocket::config). By default,\n//! configuration can be provided in `Rocket.toml`:\n//!\n//! ```toml\n//! [default.databases.db_name]\n//! url = \"db.sqlite\"\n//!\n//! # Only `url` is required. These have sane defaults and are optional.\n//! min_connections = 64\n//! max_connections = 1024\n//! connect_timeout = 5\n//! idle_timeout = 120\n//!\n//! # This option is only supported by the `sqlx_sqlite` driver.\n//! extensions = [\"memvfs\", \"rot13\"]\n//! ```\n//!\n//! Or via environment variables:\n//!\n//! ```sh\n//! ROCKET_DATABASES='{db_name={url=\"db.sqlite\",idle_timeout=120}}'\n//! ```\n//!\n//! See [`Config`] for details on configuration parameters.\n//!\n//! **Note:** `deadpool` and `diesel` drivers do not support and thus ignore the\n//! `min_connections` value.\n//!\n//! ## Driver Defaults\n//!\n//! Some drivers provide configuration defaults different from the underlying\n//! database's defaults. A best-effort attempt is made to document those\n//! differences below:\n//!\n//! * `sqlx_sqlite`\n//!\n//! - foreign keys : `enabled`\n//! - journal mode : `WAL`\n//! - create-missing : `enabled`\n//! - synchronous : `full` (even when `WAL`)\n//! - busy timeout : `connection_timeout`\n//!\n//! * `sqlx_postgres`\n//!\n//! - sslmode : `prefer`\n//! - statement-cache-capacity : `100`\n//! - user : result of `whoami`\n//!\n//! * `sqlx_mysql`\n//!\n//! - sslmode : `PREFERRED`\n//! - statement-cache-capacity : `100`\n//!\n//! # Extending\n//!\n//! Any database driver can implement support for this library by implementing\n//! the [`Pool`] trait.\n\n#![doc(html_root_url = \"https://api.rocket.rs/master/rocket_db_pools\")]\n#![doc(html_favicon_url = \"https://rocket.rs/images/favicon.ico\")]\n#![doc(html_logo_url = \"https://rocket.rs/images/logo-boxed.png\")]\n\n#![deny(missing_docs)]\n\npub use rocket;\n\n/// Re-export of the `figment` crate.\n#[doc(inline)]\npub use rocket::figment;\n\n#[cfg(any(feature = \"diesel_postgres\", feature = \"diesel_mysql\"))] pub mod diesel;\n#[cfg(feature = \"deadpool_postgres\")] pub use deadpool_postgres;\n#[cfg(feature = \"deadpool_redis\")] pub use deadpool_redis;\n#[cfg(feature = \"mongodb\")] pub use mongodb;\n#[cfg(feature = \"sqlx\")] pub use sqlx;\n\nmod database;\nmod error;\nmod pool;\nmod config;\n\npub use self::database::{Connection, Database, Initializer};\npub use self::error::Error;\npub use self::pool::Pool;\npub use self::config::Config;\n\npub use rocket_db_pools_codegen::*;\n" }, { "path": "contrib/db_pools/lib/src/pool.rs", "content": "use rocket::figment::Figment;\n\n#[allow(unused_imports)]\nuse {std::time::Duration, crate::{Error, Config}};\n\n/// Generic [`Database`](crate::Database) driver connection pool trait.\n///\n/// This trait provides a generic interface to various database pooling\n/// implementations in the Rust ecosystem. It can be implemented by anyone, but\n/// this crate provides implementations for common drivers.\n///\n/// **Implementations of this trait outside of this crate should be rare. You\n/// _do not_ need to implement this trait or understand its specifics to use\n/// this crate.**\n///\n/// ## Async Trait\n///\n/// [`Pool`] is an _async_ trait. Implementations of `Pool` must be decorated\n/// with an attribute of `#[async_trait]`:\n///\n/// ```rust\n/// # #[macro_use] extern crate rocket;\n/// use rocket::figment::Figment;\n/// use rocket_db_pools::Pool;\n///\n/// # struct MyPool;\n/// # type Connection = ();\n/// # type Error = std::convert::Infallible;\n/// #[rocket::async_trait]\n/// impl Pool for MyPool {\n/// type Connection = Connection;\n///\n/// type Error = Error;\n///\n/// async fn init(figment: &Figment) -> Result {\n/// todo!(\"initialize and return an instance of the pool\");\n/// }\n///\n/// async fn get(&self) -> Result {\n/// todo!(\"fetch one connection from the pool\");\n/// }\n///\n/// async fn close(&self) {\n/// todo!(\"gracefully shutdown connection pool\");\n/// }\n/// }\n/// ```\n///\n/// ## Implementing\n///\n/// Implementations of `Pool` typically trace the following outline:\n///\n/// 1. The `Error` associated type is set to [`Error`].\n///\n/// 2. A [`Config`] is [extracted](Figment::extract()) from the `figment`\n/// passed to init.\n///\n/// 3. The pool is initialized and returned in `init()`, wrapping\n/// initialization errors in [`Error::Init`].\n///\n/// 4. A connection is retrieved in `get()`, wrapping errors in\n/// [`Error::Get`].\n///\n/// Concretely, this looks like:\n///\n/// ```rust\n/// use rocket::figment::Figment;\n/// use rocket_db_pools::{Pool, Config, Error};\n/// #\n/// # type InitError = std::convert::Infallible;\n/// # type GetError = std::convert::Infallible;\n/// # type Connection = ();\n/// #\n/// # struct MyPool(Config);\n/// # impl MyPool {\n/// # fn new(c: Config) -> Result {\n/// # Ok(Self(c))\n/// # }\n/// #\n/// # fn acquire(&self) -> Result {\n/// # Ok(())\n/// # }\n/// #\n/// # async fn shutdown(&self) { }\n/// # }\n///\n/// #[rocket::async_trait]\n/// impl Pool for MyPool {\n/// type Connection = Connection;\n///\n/// type Error = Error;\n///\n/// async fn init(figment: &Figment) -> Result {\n/// // Extract the config from `figment`.\n/// let config: Config = figment.extract()?;\n///\n/// // Read config values, initialize `MyPool`. Map errors of type\n/// // `InitError` to `Error` with `Error::Init`.\n/// let pool = MyPool::new(config).map_err(Error::Init)?;\n///\n/// // Return the fully initialized pool.\n/// Ok(pool)\n/// }\n///\n/// async fn get(&self) -> Result {\n/// // Get one connection from the pool, here via an `acquire()` method.\n/// // Map errors of type `GetError` to `Error<_, GetError>`.\n/// self.acquire().map_err(Error::Get)\n/// }\n///\n/// async fn close(&self) {\n/// self.shutdown().await;\n/// }\n/// }\n/// ```\n#[rocket::async_trait]\npub trait Pool: Sized + Send + 'static {\n /// The connection type managed by this pool, returned by [`Self::get()`].\n type Connection;\n\n /// The error type returned by [`Self::init()`] and [`Self::get()`].\n type Error: std::error::Error;\n\n /// Constructs a pool from a [Value](rocket::figment::value::Value).\n ///\n /// It is up to each implementor of `Pool` to define its accepted\n /// configuration value(s) via the `Config` associated type. Most\n /// integrations provided in `rocket_db_pools` use [`Config`], which\n /// accepts a (required) `url` and an (optional) `pool_size`.\n ///\n /// ## Errors\n ///\n /// This method returns an error if the configuration is not compatible, or\n /// if creating a pool failed due to an unavailable database server,\n /// insufficient resources, or another database-specific error.\n async fn init(figment: &Figment) -> Result;\n\n /// Asynchronously retrieves a connection from the factory or pool.\n ///\n /// ## Errors\n ///\n /// This method returns an error if a connection could not be retrieved,\n /// such as a preconfigured timeout elapsing or when the database server is\n /// unavailable.\n async fn get(&self) -> Result;\n\n /// Shutdown the connection pool, disallowing any new connections from being\n /// retrieved and waking up any tasks with active connections.\n ///\n /// The returned future may either resolve when all connections are known to\n /// have closed or at any point prior. Details are implementation specific.\n async fn close(&self);\n}\n\n#[cfg(feature = \"deadpool\")]\nmod deadpool_postgres {\n use deadpool::{Runtime, managed::{Manager, Pool, PoolError, Object}};\n use super::{Duration, Error, Config, Figment};\n\n #[cfg(feature = \"diesel\")]\n use diesel_async::pooled_connection::AsyncDieselConnectionManager;\n\n pub trait DeadManager: Manager + Sized + Send + 'static {\n fn new(config: &Config) -> Result;\n }\n\n #[cfg(feature = \"deadpool_postgres\")]\n impl DeadManager for deadpool_postgres::Manager {\n fn new(config: &Config) -> Result {\n Ok(Self::new(config.url.parse()?, deadpool_postgres::tokio_postgres::NoTls))\n }\n }\n\n #[cfg(feature = \"deadpool_redis\")]\n impl DeadManager for deadpool_redis::Manager {\n fn new(config: &Config) -> Result {\n Self::new(config.url.as_str())\n }\n }\n\n #[cfg(feature = \"diesel_postgres\")]\n impl DeadManager for AsyncDieselConnectionManager {\n fn new(config: &Config) -> Result {\n Ok(Self::new(config.url.as_str()))\n }\n }\n\n #[cfg(feature = \"diesel_mysql\")]\n impl DeadManager for AsyncDieselConnectionManager {\n fn new(config: &Config) -> Result {\n Ok(Self::new(config.url.as_str()))\n }\n }\n\n #[rocket::async_trait]\n impl>> crate::Pool for Pool\n where M::Type: Send, C: Send + 'static, M::Error: std::error::Error\n {\n type Error = Error>;\n\n type Connection = C;\n\n async fn init(figment: &Figment) -> Result {\n let config: Config = figment.extract()?;\n let manager = M::new(&config).map_err(|e| Error::Init(e.into()))?;\n\n Pool::builder(manager)\n .max_size(config.max_connections)\n .wait_timeout(Some(Duration::from_secs(config.connect_timeout)))\n .create_timeout(Some(Duration::from_secs(config.connect_timeout)))\n .recycle_timeout(config.idle_timeout.map(Duration::from_secs))\n .runtime(Runtime::Tokio1)\n .build()\n .map_err(|_| Error::Init(PoolError::NoRuntimeSpecified))\n }\n\n async fn get(&self) -> Result {\n self.get().await.map_err(Error::Get)\n }\n\n async fn close(&self) {\n >::close(self)\n }\n }\n}\n\n#[cfg(feature = \"sqlx\")]\nmod sqlx {\n use sqlx::ConnectOptions;\n use super::{Duration, Error, Config, Figment};\n use rocket::tracing::level_filters::LevelFilter;\n\n type Options = <::Connection as sqlx::Connection>::Options;\n\n // Provide specialized configuration for particular databases.\n fn specialize(__options: &mut dyn std::any::Any, __config: &Config) {\n #[cfg(feature = \"sqlx_sqlite\")]\n if let Some(o) = __options.downcast_mut::() {\n *o = std::mem::take(o)\n .busy_timeout(Duration::from_secs(__config.connect_timeout))\n .create_if_missing(true);\n\n if let Some(ref exts) = __config.extensions {\n for ext in exts {\n *o = std::mem::take(o).extension(ext.clone());\n }\n }\n }\n }\n\n #[rocket::async_trait]\n impl crate::Pool for sqlx::Pool {\n type Error = Error;\n\n type Connection = sqlx::pool::PoolConnection;\n\n async fn init(figment: &Figment) -> Result {\n let config = figment.extract::()?;\n let mut opts = config.url.parse::>().map_err(Error::Init)?;\n specialize(&mut opts, &config);\n\n opts = opts.disable_statement_logging();\n if let Ok(value) = figment.find_value(rocket::Config::LOG_LEVEL) {\n if let Some(level) = value.as_str().and_then(|v| v.parse().ok()) {\n let log_level = match level {\n LevelFilter::OFF => log::LevelFilter::Off,\n LevelFilter::ERROR => log::LevelFilter::Error,\n LevelFilter::WARN => log::LevelFilter::Warn,\n LevelFilter::INFO => log::LevelFilter::Info,\n LevelFilter::DEBUG => log::LevelFilter::Debug,\n LevelFilter::TRACE => log::LevelFilter::Trace,\n };\n\n opts = opts.log_statements(log_level)\n .log_slow_statements(log_level, Duration::default());\n }\n }\n\n Ok(sqlx::pool::PoolOptions::new()\n .max_connections(config.max_connections as u32)\n .acquire_timeout(Duration::from_secs(config.connect_timeout))\n .idle_timeout(config.idle_timeout.map(Duration::from_secs))\n .min_connections(config.min_connections.unwrap_or_default())\n .connect_lazy_with(opts))\n }\n\n async fn get(&self) -> Result {\n self.acquire().await.map_err(Error::Get)\n }\n\n async fn close(&self) {\n >::close(self).await;\n }\n }\n}\n\n#[cfg(feature = \"mongodb\")]\nmod mongodb {\n use mongodb::{Client, options::ClientOptions};\n use super::{Duration, Error, Config, Figment};\n\n #[rocket::async_trait]\n impl crate::Pool for Client {\n type Error = Error;\n\n type Connection = Client;\n\n async fn init(figment: &Figment) -> Result {\n let config = figment.extract::()?;\n let mut opts = ClientOptions::parse(&config.url).await.map_err(Error::Init)?;\n opts.min_pool_size = config.min_connections;\n opts.max_pool_size = Some(config.max_connections as u32);\n opts.max_idle_time = config.idle_timeout.map(Duration::from_secs);\n opts.connect_timeout = Some(Duration::from_secs(config.connect_timeout));\n opts.server_selection_timeout = Some(Duration::from_secs(config.connect_timeout));\n Client::with_options(opts).map_err(Error::Init)\n }\n\n async fn get(&self) -> Result {\n Ok(self.clone())\n }\n\n async fn close(&self) {\n // nothing to do for mongodb\n }\n }\n}\n" }, { "path": "contrib/db_pools/lib/tests/databases.rs", "content": "macro_rules! check_types_match {\n ($feature:expr, $name:ident, $Pool:ty, $Conn:ty $(,)?) => (\n #[cfg(feature = $feature)]\n mod $name {\n use rocket::*;\n use rocket_db_pools::{Connection, Database};\n\n #[derive(Database)]\n #[database(\"foo\")]\n struct Db($Pool);\n\n #[get(\"/\")]\n fn _db(conn: Connection) {\n let _: &$Conn = &*conn;\n }\n }\n )\n}\n\ncheck_types_match!(\n \"deadpool_postgres\",\n deadpool_postgres,\n deadpool_postgres::Pool,\n deadpool_postgres::ClientWrapper,\n);\n\ncheck_types_match!(\n \"deadpool_redis\",\n deadpool_redis,\n deadpool_redis::Pool,\n deadpool_redis::Connection,\n);\n\ncheck_types_match!(\n \"sqlx_postgres\",\n sqlx_postgres,\n sqlx::PgPool,\n sqlx::pool::PoolConnection,\n);\n\ncheck_types_match!(\n \"sqlx_mysql\",\n sqlx_mysql,\n sqlx::MySqlPool,\n sqlx::pool::PoolConnection,\n);\n\ncheck_types_match!(\n \"sqlx_sqlite\",\n sqlx_sqlite,\n sqlx::SqlitePool,\n sqlx::pool::PoolConnection,\n);\n\ncheck_types_match!(\n \"mongodb\",\n mongodb,\n mongodb::Client,\n mongodb::Client,\n);\n" }, { "path": "contrib/dyn_templates/Cargo.toml", "content": "[package]\nname = \"rocket_dyn_templates\"\nversion = \"0.1.0\"\nauthors = [\"Sergio Benitez \"]\ndescription = \"Dynamic templating engine integration for Rocket.\"\ndocumentation = \"https://api.rocket.rs/master/rocket_dyn_templates/\"\nhomepage = \"https://rocket.rs\"\nrepository = \"https://github.com/rwf2/Rocket/tree/master/contrib/dyn_templates\"\nreadme = \"README.md\"\nkeywords = [\"rocket\", \"framework\", \"templates\", \"templating\", \"engine\"]\nlicense = \"MIT OR Apache-2.0\"\nedition = \"2021\"\nrust-version = \"1.75\"\n\n[lints]\nworkspace = true\n\n[features]\ntera = [\"dep:tera\"]\nhandlebars = [\"dep:handlebars\"]\nminijinja = [\"dep:minijinja\"]\n\n[dependencies]\nwalkdir = \"2.4\"\nnotify = \"7\"\nnormpath = \"1\"\n\ntera = { version = \"1.19.0\", optional = true }\nhandlebars = { version = \"6.0\", optional = true }\n\n[dependencies.minijinja]\nversion = \"2.0.1\"\noptional = true\nfeatures = [\"loader\", \"speedups\", \"json\", \"urlencode\"]\n\n[dependencies.rocket]\nversion = \"0.6.0-dev\"\npath = \"../../core/lib\"\ndefault-features = false\n\n[dev-dependencies]\npretty_assertions = \"1.4\"\n\n[package.metadata.docs.rs]\nall-features = true\n" }, { "path": "contrib/dyn_templates/README.md", "content": "# `dyn_templates` [![ci.svg]][ci] [![crates.io]][crate] [![docs.svg]][crate docs]\n\n[crates.io]: https://img.shields.io/crates/v/rocket_dyn_templates.svg\n[crate]: https://crates.io/crates/rocket_dyn_templates\n[docs.svg]: https://img.shields.io/badge/web-master-red.svg?style=flat&label=docs&colorB=d33847\n[crate docs]: https://api.rocket.rs/master/rocket_dyn_templates\n[ci.svg]: https://github.com/rwf2/Rocket/workflows/CI/badge.svg\n[ci]: https://github.com/rwf2/Rocket/actions\n\nThis crate adds support for dynamic template rendering to Rocket. It\nautomatically discovers templates, provides a `Responder` to render templates,\nand automatically reloads templates when compiled in debug mode. It supports [Handlebars], [Tera] and [MiniJinja].\n\n[Tera]: https://docs.rs/crate/tera/1\n[Handlebars]: https://docs.rs/crate/handlebars/5\n[MiniJinja]: https://docs.rs/crate/minijinja/2.0.1\n\n# Usage\n\n 1. Enable the `rocket_dyn_templates` feature corresponding to your templating\n engine(s) of choice:\n\n ```toml\n [dependencies.rocket_dyn_templates]\n version = \"0.1.0\"\n features = [\"handlebars\", \"tera\", \"minijinja\"]\n ```\n\n 1. Write your template files in Handlebars (`.hbs`) and/or Tera (`.tera`) in\n the configurable `template_dir` directory (default:\n `{rocket_root}/templates`).\n\n 2. Attach `Template::fairing()` and return a `Template` using\n `Template::render()`, supplying the name of the template file **minus the\n last two extensions**:\n\n ```rust\n use rocket_dyn_templates::{Template, context};\n\n #[get(\"/\")]\n fn index() -> Template {\n Template::render(\"template-name\", context! { field: \"value\" })\n }\n\n #[launch]\n fn rocket() -> _ {\n rocket::build().attach(Template::fairing())\n }\n ```\n\nSee the [crate docs] for full details.\n" }, { "path": "contrib/dyn_templates/src/context.rs", "content": "use std::path::{Path, PathBuf};\nuse std::collections::HashMap;\nuse std::error::Error;\n\nuse crate::engine::Engines;\nuse crate::template::TemplateInfo;\n\nuse rocket::http::ContentType;\nuse normpath::PathExt;\n\npub(crate) type Callback =\n Box Result<(), Box> + Send + Sync + 'static>;\n\npub(crate) struct Context {\n /// The root of the template directory.\n pub root: PathBuf,\n /// Mapping from template name to its information.\n pub templates: HashMap,\n /// Loaded template engines\n pub engines: Engines,\n}\n\npub(crate) use self::manager::ContextManager;\n\nimpl Context {\n /// Load all of the templates at `root`, initialize them using the relevant\n /// template engine, and store all of the initialized state in a `Context`\n /// structure, which is returned if all goes well.\n pub fn initialize(root: &Path, callback: &Callback) -> Option {\n fn is_file_with_ext(entry: &walkdir::DirEntry, ext: &str) -> bool {\n let is_file = entry.file_type().is_file();\n let has_ext = entry.path().extension().map_or(false, |e| e == ext);\n is_file && has_ext\n }\n\n let root = match root.normalize() {\n Ok(root) => root.into_path_buf(),\n Err(e) => {\n error!(\"Invalid template directory '{}': {}.\", root.display(), e);\n return None;\n }\n };\n\n let mut templates: HashMap = HashMap::new();\n for &ext in Engines::ENABLED_EXTENSIONS {\n for entry in walkdir::WalkDir::new(&root).follow_links(true) {\n let entry = match entry {\n Ok(entry) if is_file_with_ext(&entry, ext) => entry,\n Ok(_) | Err(_) => continue,\n };\n\n let (template, data_type_str) = split_path(&root, entry.path());\n if let Some(info) = templates.get(&*template) {\n warn!(\n %template,\n first_path = %entry.path().display(),\n second_path = info.path.as_ref().map(|p| display(p.display())),\n data_type = %info.data_type,\n \"Template name '{template}' can refer to multiple templates.\\n\\\n First path will be used. Second path is ignored.\"\n );\n\n continue;\n }\n\n let data_type = data_type_str.as_ref()\n .and_then(|ext| ContentType::from_extension(ext))\n .unwrap_or(ContentType::Text);\n\n templates.insert(template, TemplateInfo {\n path: Some(entry.into_path()),\n engine_ext: ext,\n data_type,\n });\n }\n }\n\n let mut engines = Engines::init(&templates)?;\n if let Err(reason) = callback(&mut engines) {\n error!(%reason, \"template customization callback failed\");\n return None;\n }\n\n for (name, engine_ext) in engines.templates() {\n if !templates.contains_key(name) {\n let data_type = Path::new(name).extension()\n .and_then(|osstr| osstr.to_str())\n .and_then(ContentType::from_extension)\n .unwrap_or(ContentType::Text);\n\n let info = TemplateInfo { path: None, engine_ext, data_type };\n templates.insert(name.to_string(), info);\n }\n }\n\n Some(Context { root, templates, engines })\n }\n}\n\n#[cfg(not(debug_assertions))]\nmod manager {\n use std::ops::Deref;\n use super::Context;\n\n /// Wraps a Context. With `cfg(debug_assertions)` active, this structure\n /// additionally provides a method to reload the context at runtime.\n pub(crate) struct ContextManager(Context);\n\n impl ContextManager {\n pub fn new(ctxt: Context) -> ContextManager {\n ContextManager(ctxt)\n }\n\n pub fn context<'a>(&'a self) -> impl Deref + 'a {\n &self.0\n }\n\n pub fn is_reloading(&self) -> bool {\n false\n }\n }\n}\n\n#[cfg(debug_assertions)]\nmod manager {\n use std::ops::{Deref, DerefMut};\n use std::sync::{RwLock, Mutex};\n use std::sync::mpsc::{channel, Receiver};\n\n use notify::{recommended_watcher, Error, Event, RecommendedWatcher, RecursiveMode, Watcher};\n\n use super::{Callback, Context};\n\n /// Wraps a Context. With `cfg(debug_assertions)` active, this structure\n /// additionally provides a method to reload the context at runtime.\n pub(crate) struct ContextManager {\n /// The current template context, inside an RwLock so it can be updated.\n context: RwLock,\n /// A filesystem watcher and the receive queue for its events.\n watcher: Option<(RecommendedWatcher, Mutex>>)>,\n }\n\n impl ContextManager {\n pub fn new(ctxt: Context) -> ContextManager {\n let (tx, rx) = channel();\n let watcher = recommended_watcher(tx).and_then(|mut watcher| {\n watcher.watch(&ctxt.root.canonicalize()?, RecursiveMode::Recursive)?;\n Ok(watcher)\n });\n\n let watcher = match watcher {\n Ok(watcher) => Some((watcher, Mutex::new(rx))),\n Err(e) => {\n warn!(\"live template reloading initialization failed: {e}\\n\\\n live template reloading is unavailable\");\n None\n }\n };\n\n ContextManager { watcher, context: RwLock::new(ctxt), }\n }\n\n pub fn context(&self) -> impl Deref + '_ {\n self.context.read().unwrap()\n }\n\n pub fn is_reloading(&self) -> bool {\n self.watcher.is_some()\n }\n\n fn context_mut(&self) -> impl DerefMut + '_ {\n self.context.write().unwrap()\n }\n\n /// Checks whether any template files have changed on disk. If there\n /// have been changes since the last reload, all templates are\n /// reinitialized from disk and the user's customization callback is run\n /// again.\n pub fn reload_if_needed(&self, callback: &Callback) {\n let templates_changes = self.watcher.as_ref()\n .map(|(_, rx)| rx.lock().expect(\"fsevents lock\").try_iter().count() > 0);\n\n if let Some(true) = templates_changes {\n debug!(\"template change detected: reloading templates\");\n let root = self.context().root.clone();\n if let Some(new_ctxt) = Context::initialize(&root, callback) {\n *self.context_mut() = new_ctxt;\n } else {\n warn!(\"error while reloading template\\n\\\n existing templates will remain active.\")\n };\n }\n }\n }\n}\n\n/// Removes the file path's extension or does nothing if there is none.\nfn remove_extension(path: &Path) -> PathBuf {\n let stem = match path.file_stem() {\n Some(stem) => stem,\n None => return path.to_path_buf()\n };\n\n match path.parent() {\n Some(parent) => parent.join(stem),\n None => PathBuf::from(stem)\n }\n}\n\n/// Splits a path into a name that may be used to identify the template, and the\n/// template's data type, if any.\nfn split_path(root: &Path, path: &Path) -> (String, Option) {\n let rel_path = path.strip_prefix(root).unwrap().to_path_buf();\n let path_no_ext = remove_extension(&rel_path);\n let data_type = path_no_ext.extension();\n let mut name = remove_extension(&path_no_ext).to_string_lossy().into_owned();\n\n // Ensure template name consistency on Windows systems\n if cfg!(windows) {\n name = name.replace('\\\\', \"/\");\n }\n\n (name, data_type.map(|d| d.to_string_lossy().into_owned()))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn template_path_index_html() {\n for root in &[\"/\", \"/a/b/c/\", \"/a/b/c/d/\", \"/a/\"] {\n for filename in &[\"index.html.hbs\", \"index.html.tera\"] {\n let path = Path::new(root).join(filename);\n let (name, data_type) = split_path(Path::new(root), &path);\n\n assert_eq!(name, \"index\");\n assert_eq!(data_type, Some(\"html\".into()));\n }\n }\n }\n\n #[test]\n fn template_path_subdir_index_html() {\n for root in &[\"/\", \"/a/b/c/\", \"/a/b/c/d/\", \"/a/\"] {\n for sub in &[\"a/\", \"a/b/\", \"a/b/c/\", \"a/b/c/d/\"] {\n for filename in &[\"index.html.hbs\", \"index.html.tera\"] {\n let path = Path::new(root).join(sub).join(filename);\n let (name, data_type) = split_path(Path::new(root), &path);\n\n let expected_name = format!(\"{}index\", sub);\n assert_eq!(name, expected_name.as_str());\n assert_eq!(data_type, Some(\"html\".into()));\n }\n }\n }\n }\n\n #[test]\n fn template_path_doc_examples() {\n fn name_for(path: &str) -> String {\n split_path(Path::new(\"templates/\"), &Path::new(\"templates/\").join(path)).0\n }\n\n assert_eq!(name_for(\"index.html.hbs\"), \"index\");\n assert_eq!(name_for(\"index.tera\"), \"index\");\n assert_eq!(name_for(\"index.hbs\"), \"index\");\n assert_eq!(name_for(\"dir/index.hbs\"), \"dir/index\");\n assert_eq!(name_for(\"dir/index.html.tera\"), \"dir/index\");\n assert_eq!(name_for(\"index.template.html.hbs\"), \"index.template\");\n assert_eq!(name_for(\"subdir/index.template.html.hbs\"), \"subdir/index.template\");\n }\n}\n" }, { "path": "contrib/dyn_templates/src/engine/handlebars.rs", "content": "use std::path::Path;\n\nuse handlebars::Handlebars;\nuse rocket::serde::Serialize;\n\nuse crate::engine::Engine;\n\nimpl Engine for Handlebars<'static> {\n const EXT: &'static str = \"hbs\";\n\n fn init<'a>(templates: impl Iterator) -> Option {\n let mut hb = Handlebars::new();\n let mut ok = true;\n for (template, path) in templates {\n if let Err(e) = hb.register_template_file(template, path) {\n error!(template, path = %path.display(),\n \"failed to register Handlebars template: {e}\");\n\n ok = false;\n }\n }\n\n ok.then_some(hb)\n }\n\n fn render(&self, template: &str, context: C) -> Option {\n if self.get_template(template).is_none() {\n error!(template, \"requested Handlebars template does not exist.\");\n return None;\n }\n\n Handlebars::render(self, template, &context)\n .map_err(|e| error!(\"Handlebars render error: {}\", e))\n .ok()\n }\n}\n" }, { "path": "contrib/dyn_templates/src/engine/minijinja.rs", "content": "use std::sync::Arc;\nuse std::path::Path;\nuse std::collections::HashMap;\n\nuse rocket::serde::Serialize;\nuse minijinja::{Environment, Error, ErrorKind, AutoEscape};\n\nuse crate::engine::Engine;\n\nimpl Engine for Environment<'static> {\n const EXT: &'static str = \"j2\";\n\n fn init<'a>(templates: impl Iterator) -> Option {\n let _templates = Arc::new(templates\n .map(|(k, p)| (k.to_owned(), p.to_owned()))\n .collect::>());\n\n let templates = _templates.clone();\n let mut env = Environment::new();\n env.set_loader(move |name| {\n let Some(path) = templates.get(name) else {\n return Ok(None);\n };\n\n match std::fs::read_to_string(path) {\n Ok(result) => Ok(Some(result)),\n Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),\n Err(e) => Err(\n Error::new(ErrorKind::InvalidOperation, \"template read failed\").with_source(e)\n ),\n }\n });\n\n let templates = _templates.clone();\n env.set_auto_escape_callback(move |name| {\n templates.get(name)\n .and_then(|path| path.to_str())\n .map(minijinja::default_auto_escape_callback)\n .unwrap_or(AutoEscape::None)\n });\n\n Some(env)\n }\n\n fn render(&self, template: &str, context: C) -> Option {\n let Ok(templ) = self.get_template(template) else {\n error!(template, \"requested template does not exist\");\n return None;\n };\n\n match templ.render(context) {\n Ok(result) => Some(result),\n Err(e) => {\n span_error!(\"templating\", template, \"failed to render Minijinja template\" => {\n let mut error = Some(&e as &dyn std::error::Error);\n while let Some(err) = error {\n error!(\"{err}\");\n error = err.source();\n }\n });\n\n None\n }\n }\n }\n}\n" }, { "path": "contrib/dyn_templates/src/engine/mod.rs", "content": "use std::path::Path;\nuse std::collections::HashMap;\n\nuse rocket::serde::Serialize;\n\nuse crate::template::TemplateInfo;\n\n#[cfg(feature = \"tera\")]\nmod tera;\n#[cfg(feature = \"tera\")]\nuse ::tera::Tera;\n\n#[cfg(feature = \"handlebars\")]\nmod handlebars;\n#[cfg(feature = \"handlebars\")]\nuse ::handlebars::Handlebars;\n\n#[cfg(feature = \"minijinja\")]\nmod minijinja;\n#[cfg(feature = \"minijinja\")]\nuse ::minijinja::Environment;\n\npub(crate) trait Engine: Send + Sync + Sized + 'static {\n const EXT: &'static str;\n\n fn init<'a>(templates: impl Iterator) -> Option;\n fn render(&self, name: &str, context: C) -> Option;\n}\n\n/// A structure exposing access to templating engines.\n///\n/// Calling methods on the exposed template engine types may require importing\n/// types from the respective templating engine library. These types should be\n/// imported from the reexported crate at the root of `rocket_dyn_templates` to\n/// avoid version mismatches. For instance, when registering a Tera filter, the\n/// [`tera::Value`] and [`tera::Result`] types are required. Import them from\n/// `rocket_dyn_templates::tera`. The example below illustrates this:\n///\n/// ```rust\n/// # #[cfg(feature = \"tera\")] {\n/// use std::collections::HashMap;\n///\n/// use rocket_dyn_templates::{Template, Engines};\n/// use rocket_dyn_templates::tera::{self, Value};\n///\n/// fn my_filter(value: &Value, _: &HashMap) -> tera::Result {\n/// # /*\n/// ...\n/// # */ unimplemented!();\n/// }\n///\n/// fn main() {\n/// rocket::build()\n/// // ...\n/// .attach(Template::custom(|engines: &mut Engines| {\n/// engines.tera.register_filter(\"my_filter\", my_filter);\n/// }))\n/// // ...\n/// # ;\n/// }\n/// # }\n/// ```\n///\n/// [`tera::Value`]: crate::tera::Value\n/// [`tera::Result`]: crate::tera::Result\npub struct Engines {\n /// A `Tera` templating engine.\n ///\n /// This field is only available when the `tera` feature is enabled. When\n /// calling methods on the `Tera` instance, ensure you use types imported\n /// from `rocket_dyn_templates::tera` to avoid version mismatches.\n #[cfg(feature = \"tera\")]\n pub tera: Tera,\n\n /// The Handlebars templating engine.\n ///\n /// This field is only available when the `handlebars` feature is enabled.\n /// When calling methods on the `Handlebars` instance, ensure you use types\n /// imported from `rocket_dyn_templates::handlebars` to avoid version\n /// mismatches.\n #[cfg(feature = \"handlebars\")]\n pub handlebars: Handlebars<'static>,\n\n /// The minijinja templating engine.\n ///\n /// This field is only available when the `minijinja` feature is enabled.\n /// When calling methods on the [`Environment`] instance, ensure you use\n /// types imported from `rocket_dyn_templates::minijinja` to avoid version\n /// mismatches.\n #[cfg(feature = \"minijinja\")]\n pub minijinja: Environment<'static>,\n}\n\nimpl Engines {\n pub(crate) const ENABLED_EXTENSIONS: &'static [&'static str] = &[\n #[cfg(feature = \"tera\")] Tera::EXT,\n #[cfg(feature = \"handlebars\")] Handlebars::EXT,\n #[cfg(feature = \"minijinja\")] Environment::EXT,\n ];\n\n pub(crate) fn init(templates: &HashMap) -> Option {\n fn inner(templates: &HashMap) -> Option {\n let named_templates = templates.iter()\n .filter(|&(_, i)| i.engine_ext == E::EXT)\n .filter_map(|(k, i)| Some((k.as_str(), i.path.as_ref()?)))\n .map(|(k, p)| (k, p.as_path()));\n\n E::init(named_templates)\n }\n\n Some(Engines {\n #[cfg(feature = \"tera\")]\n tera: match inner::(templates) {\n Some(tera) => tera,\n None => return None\n },\n #[cfg(feature = \"handlebars\")]\n handlebars: match inner::>(templates) {\n Some(hb) => hb,\n None => return None\n },\n #[cfg(feature = \"minijinja\")]\n minijinja: match inner::>(templates) {\n Some(hb) => hb,\n None => return None\n },\n })\n }\n\n pub(crate) fn render(\n &self,\n name: &str,\n info: &TemplateInfo,\n context: C,\n ) -> Option {\n #[cfg(feature = \"tera\")] {\n if info.engine_ext == Tera::EXT {\n return Engine::render(&self.tera, name, context);\n }\n }\n\n #[cfg(feature = \"handlebars\")] {\n if info.engine_ext == Handlebars::EXT {\n return Engine::render(&self.handlebars, name, context);\n }\n }\n\n #[cfg(feature = \"minijinja\")] {\n if info.engine_ext == Environment::EXT {\n return Engine::render(&self.minijinja, name, context);\n }\n }\n\n None\n }\n\n /// Returns iterator over template (name, engine_extension).\n pub(crate) fn templates(&self) -> impl Iterator {\n #[cfg(feature = \"tera\")]\n let tera = self.tera.get_template_names().map(|name| (name, Tera::EXT));\n\n #[cfg(feature = \"handlebars\")]\n let handlebars = self.handlebars.get_templates().keys()\n .map(|name| (name.as_str(), Handlebars::EXT));\n\n #[cfg(feature = \"minijinja\")]\n let minijinja = self.minijinja.templates()\n .map(|(name, _)| (name, Environment::EXT));\n\n #[cfg(not(feature = \"tera\"))] let tera = std::iter::empty();\n #[cfg(not(feature = \"handlebars\"))] let handlebars = std::iter::empty();\n #[cfg(not(feature = \"minijinja\"))] let minijinja = std::iter::empty();\n\n tera.chain(handlebars).chain(minijinja)\n }\n}\n" }, { "path": "contrib/dyn_templates/src/engine/tera.rs", "content": "use std::path::Path;\nuse std::error::Error;\n\nuse tera::{Context, Tera};\nuse rocket::serde::Serialize;\n\nuse crate::engine::Engine;\n\nimpl Engine for Tera {\n const EXT: &'static str = \"tera\";\n\n fn init<'a>(templates: impl Iterator) -> Option {\n // Create the Tera instance.\n let mut tera = Tera::default();\n let ext = [\".html.tera\", \".htm.tera\", \".xml.tera\", \".html\", \".htm\", \".xml\"];\n tera.autoescape_on(ext.to_vec());\n\n // Collect into a tuple of (name, path) for Tera. If we register one at\n // a time, it will complain about unregistered base templates.\n let files = templates.map(|(name, path)| (path, Some(name)));\n\n // Finally try to tell Tera about all of the templates.\n if let Err(e) = tera.add_template_files(files) {\n span_error!(\"templating\", \"Tera templating initialization failed\" => {\n let mut error = Some(&e as &dyn Error);\n while let Some(err) = error {\n error!(\"{err}\");\n error = err.source();\n }\n });\n\n None\n } else {\n Some(tera)\n }\n }\n\n fn render(&self, template: &str, context: C) -> Option {\n if self.get_template(template).is_err() {\n error!(template, \"requested template does not exist\");\n return None;\n };\n\n let tera_ctx = Context::from_serialize(context)\n .map_err(|e| error!(\"Tera context error: {}.\", e))\n .ok()?;\n\n match Tera::render(self, template, &tera_ctx) {\n Ok(string) => Some(string),\n Err(e) => {\n span_error!(\"templating\", template, \"failed to render Tera template\" => {\n let mut error = Some(&e as &dyn Error);\n while let Some(err) = error {\n error!(\"{err}\");\n error = err.source();\n }\n });\n\n None\n }\n }\n }\n}\n" }, { "path": "contrib/dyn_templates/src/fairing.rs", "content": "use rocket::{Rocket, Build, Orbit};\nuse rocket::fairing::{self, Fairing, Info, Kind};\nuse rocket::figment::{Source, value::magic::RelativePathBuf};\nuse rocket::trace::Trace;\n\nuse crate::context::{Callback, Context, ContextManager};\nuse crate::template::DEFAULT_TEMPLATE_DIR;\nuse crate::engine::Engines;\n\n/// The TemplateFairing initializes the template system on attach, running\n/// custom_callback after templates have been loaded. In debug mode, the fairing\n/// checks for modifications to templates before every request and reloads them\n/// if necessary.\npub struct TemplateFairing {\n /// The user-provided customization callback, allowing the use of\n /// functionality specific to individual template engines. In debug mode,\n /// this callback might be run multiple times as templates are reloaded.\n pub callback: Callback,\n}\n\n#[rocket::async_trait]\nimpl Fairing for TemplateFairing {\n fn info(&self) -> Info {\n let kind = Kind::Ignite | Kind::Liftoff;\n #[cfg(debug_assertions)] let kind = kind | Kind::Request;\n\n Info { kind, name: \"Templating\" }\n }\n\n /// Initializes the template context. Templates will be searched for in the\n /// `template_dir` config variable or the default ([DEFAULT_TEMPLATE_DIR]).\n /// The user's callback, if any was supplied, is called to customize the\n /// template engines. In debug mode, the `ContextManager::new` method\n /// initializes a directory watcher for auto-reloading of templates.\n async fn on_ignite(&self, rocket: Rocket) -> fairing::Result {\n let configured_dir = rocket.figment()\n .extract_inner::(\"template_dir\")\n .map(|path| path.relative());\n\n let path = match configured_dir {\n Ok(dir) => dir,\n Err(e) if e.missing() => DEFAULT_TEMPLATE_DIR.into(),\n Err(e) => {\n e.trace_error();\n return Err(rocket);\n }\n };\n\n if let Some(ctxt) = Context::initialize(&path, &self.callback) {\n Ok(rocket.manage(ContextManager::new(ctxt)))\n } else {\n error!(\"Template initialization failed. Aborting launch.\");\n Err(rocket)\n }\n }\n\n async fn on_liftoff(&self, rocket: &Rocket) {\n let cm = rocket.state::()\n .expect(\"Template ContextManager registered in on_ignite\");\n\n span_info!(\"templating\" => {\n info!(directory = %Source::from(&*cm.context().root));\n info!(engines = ?Engines::ENABLED_EXTENSIONS);\n });\n }\n\n #[cfg(debug_assertions)]\n async fn on_request(&self, req: &mut rocket::Request<'_>, _data: &mut rocket::Data<'_>) {\n let cm = req.rocket().state::()\n .expect(\"Template ContextManager registered in on_ignite\");\n\n cm.reload_if_needed(&self.callback);\n }\n}\n" }, { "path": "contrib/dyn_templates/src/lib.rs", "content": "//! Dynamic templating engine support for Rocket.\n//!\n//! This crate adds support for dynamic template rendering to Rocket. It\n//! automatically discovers templates, provides a `Responder` to render\n//! templates, and automatically reloads templates when compiled in debug mode.\n//! At present, it supports [Handlebars] and [Tera].\n//!\n//! # Usage\n//!\n//! 1. Depend on `rocket_dyn_templates`. Enable the feature(s) corresponding\n//! to your templating engine(s) of choice:\n//!\n//! ```toml\n//! [dependencies.rocket_dyn_templates]\n//! version = \"0.1.0\"\n//! features = [\"handlebars\", \"tera\", \"minijinja\"]\n//! ```\n//!\n//! 2. Write your templates inside of the [configurable]\n//! `${ROCKET_ROOT}/templates`. The filename _must_ end with an extension\n//! corresponding to an enabled engine. The second-to-last extension should\n//! correspond to the file's type:\n//!\n//! | Engine | Extension | Example |\n//! |--------------|-----------|--------------------------------------------|\n//! | [Tera] | `.tera` | `${ROCKET_ROOT}/templates/index.html.tera` |\n//! | [Handlebars] | `.hbs` | `${ROCKET_ROOT}/templates/index.html.hbs` |\n//! | [MiniJinja] | `.j2` | `${ROCKET_ROOT}/templates/index.html.j2` |\n//!\n//! [configurable]: #configuration\n//! [Tera]: https://docs.rs/crate/tera/1\n//! [Handlebars]: https://docs.rs/crate/handlebars/6\n//! [MiniJinja]: https://docs.rs/minijinja/2\n//!\n//! 3. Attach `Template::fairing()` and return a [`Template`] from your routes\n//! via [`Template::render()`], supplying the name of the template file\n//! **minus the last two extensions**:\n//!\n//! ```rust\n//! # #[macro_use] extern crate rocket;\n//! use rocket_dyn_templates::{Template, context};\n//!\n//! #[get(\"/\")]\n//! fn index() -> Template {\n//! Template::render(\"index\", context! { field: \"value\" })\n//! }\n//!\n//! #[launch]\n//! fn rocket() -> _ {\n//! rocket::build().attach(Template::fairing())\n//! }\n//! ```\n//!\n//! ## Configuration\n//!\n//! This crate reads one configuration parameter from the configured figment:\n//!\n//! * `template_dir` (**default: `templates/`**)\n//!\n//! A path to a directory to search for template files in. Relative paths\n//! are considered relative to the configuration file, or there is no file,\n//! the current working directory.\n//!\n//! For example, to change the default and set `template_dir` to different\n//! values based on whether the application was compiled for debug or release\n//! from a `Rocket.toml` file (read by the default figment), you might write:\n//!\n//! ```toml\n//! [debug]\n//! template_dir = \"static/templates\"\n//!\n//! [release]\n//! template_dir = \"/var/opt/www/templates\"\n//! ```\n//!\n//! **Note:** `template_dir` defaults to `templates/`. It _does not_ need to be\n//! specified if the default suffices.\n//!\n//! See the [configuration chapter] of the guide for more information on\n//! configuration.\n//!\n//! [configuration chapter]: https://rocket.rs/master/guide/configuration\n//!\n//! ## Template Naming and Content-Types\n//!\n//! Templates are rendered by _name_ via [`Template::render()`], which returns a\n//! [`Template`] responder. The _name_ of the template is the path to the\n//! template file, relative to `template_dir`, minus at most two extensions.\n//!\n//! The `Content-Type` of the response is automatically determined by the\n//! non-engine extension using [`ContentType::from_extension()`]. If there is no\n//! such extension or it is unknown, `text/plain` is used.\n//!\n//! The following table contains examples:\n//!\n//! | template path | [`Template::render()`] call | content-type |\n//! |-----------------------------------------------|-----------------------------------|--------------|\n//! | {template_dir}/index.html.hbs | `render(\"index\")` | HTML |\n//! | {template_dir}/index.tera | `render(\"index\")` | `text/plain` |\n//! | {template_dir}/index.hbs | `render(\"index\")` | `text/plain` |\n//! | {template_dir}/dir/index.hbs | `render(\"dir/index\")` | `text/plain` |\n//! | {template_dir}/dir/data.json.tera | `render(\"dir/data\")` | JSON |\n//! | {template_dir}/data.template.xml.hbs | `render(\"data.template\")` | XML |\n//! | {template_dir}/subdir/index.template.html.hbs | `render(\"subdir/index.template\")` | HTML |\n//!\n//! The recommended naming scheme is to use two extensions: one for the file\n//! type, and one for the template extension. This means that template\n//! extensions should look like: `.html.hbs`, `.html.tera`, `.xml.hbs`, and so\n//! on.\n//!\n//! [`ContentType::from_extension()`]: ../rocket/http/struct.ContentType.html#method.from_extension\n//!\n//! ### Rendering Context\n//!\n//! In addition to a name, [`Template::render()`] requires a context to use\n//! during rendering. The context can be any [`Serialize`] type that serializes\n//! to an `Object` (a dictionary) value. The [`context!`] macro can be used to\n//! create inline `Serialize`-able context objects.\n//!\n//! [`Serialize`]: rocket::serde::Serialize\n//!\n//! ```rust\n//! # #[macro_use] extern crate rocket;\n//! use rocket::serde::Serialize;\n//! use rocket_dyn_templates::{Template, context};\n//!\n//! #[get(\"/\")]\n//! fn index() -> Template {\n//! // Using the `context! { }` macro.\n//! Template::render(\"index\", context! {\n//! site_name: \"Rocket - Home Page\",\n//! version: 127,\n//! })\n//! }\n//!\n//! #[get(\"/\")]\n//! fn index2() -> Template {\n//! #[derive(Serialize)]\n//! #[serde(crate = \"rocket::serde\")]\n//! struct IndexContext {\n//! site_name: &'static str,\n//! version: u8\n//! }\n//!\n//! // Using an existing `IndexContext`, which implements `Serialize`.\n//! Template::render(\"index\", IndexContext {\n//! site_name: \"Rocket - Home Page\",\n//! version: 127,\n//! })\n//! }\n//! ```\n//!\n//! ### Discovery, Automatic Reloads, and Engine Customization\n//!\n//! As long as one of [`Template::fairing()`], [`Template::custom()`], or\n//! [`Template::try_custom()`] is [attached], any file in the configured\n//! `template_dir` ending with a known engine extension (as described in the\n//! [usage section](#usage)) can be rendered. The latter two fairings allow\n//! customizations such as registering helpers and templates from strings.\n//!\n//! _**Note:** Templates that are registered directly via [`Template::custom()`],\n//! use whatever name provided during that registration; no extensions are\n//! automatically removed._\n//!\n//! In debug mode (without the `--release` flag passed to `cargo`), templates\n//! are **automatically reloaded** from disk when changes are made. In release\n//! builds, template reloading is disabled to improve performance and cannot be\n//! enabled.\n//!\n//! [attached]: rocket::Rocket::attach()\n//!\n//! ### Metadata and Rendering to `String`\n//!\n//! The [`Metadata`] request guard allows dynamically querying templating\n//! metadata, such as whether a template is known to exist\n//! ([`Metadata::contains_template()`]), and to render templates to `String`\n//! ([`Metadata::render()`]).\n\n#![doc(html_root_url = \"https://api.rocket.rs/master/rocket_dyn_templates\")]\n#![doc(html_favicon_url = \"https://rocket.rs/images/favicon.ico\")]\n#![doc(html_logo_url = \"https://rocket.rs/images/logo-boxed.png\")]\n\n#[macro_use] extern crate rocket;\n\n#[doc(inline)]\n#[cfg(feature = \"tera\")]\n/// The tera templating engine library, reexported.\npub use tera;\n\n#[doc(inline)]\n#[cfg(feature = \"handlebars\")]\n/// The handlebars templating engine library, reexported.\npub use handlebars;\n\n#[doc(inline)]\n#[cfg(feature = \"minijinja\")]\n/// The minijinja templating engine library, reexported.\npub use minijinja;\n\n#[doc(hidden)]\npub use rocket::serde;\n\nmod engine;\nmod fairing;\nmod context;\nmod metadata;\nmod template;\n\npub use engine::Engines;\npub use metadata::Metadata;\npub use template::Template;\n" }, { "path": "contrib/dyn_templates/src/metadata.rs", "content": "use std::fmt;\nuse std::borrow::Cow;\n\nuse rocket::{Request, Rocket, Ignite, Sentinel};\nuse rocket::http::{Status, ContentType};\nuse rocket::request::{self, FromRequest};\nuse rocket::serde::Serialize;\n\nuse crate::{Template, context::ContextManager};\n\n/// Request guard for dynamically querying template metadata.\n///\n/// # Usage\n///\n/// The `Metadata` type implements Rocket's [`FromRequest`] trait, so it can be\n/// used as a request guard in any request handler.\n///\n/// ```rust\n/// # #[macro_use] extern crate rocket;\n/// # #[macro_use] extern crate rocket_dyn_templates;\n/// use rocket_dyn_templates::{Template, Metadata, context};\n///\n/// #[get(\"/\")]\n/// fn homepage(metadata: Metadata) -> Template {\n/// // Conditionally render a template if it's available.\n/// # let context = ();\n/// if metadata.contains_template(\"some-template\") {\n/// Template::render(\"some-template\", &context)\n/// } else {\n/// Template::render(\"fallback\", &context)\n/// }\n/// }\n///\n/// fn main() {\n/// rocket::build()\n/// .attach(Template::fairing())\n/// // ...\n/// # ;\n/// }\n/// ```\npub struct Metadata<'a>(&'a ContextManager);\n\nimpl Metadata<'_> {\n /// Returns `true` if the template with the given `name` is currently\n /// loaded. Otherwise, returns `false`.\n ///\n /// # Example\n ///\n /// ```rust\n /// # #[macro_use] extern crate rocket;\n /// # extern crate rocket_dyn_templates;\n /// #\n /// use rocket_dyn_templates::Metadata;\n ///\n /// #[get(\"/\")]\n /// fn handler(metadata: Metadata) {\n /// // Returns `true` if the template with name `\"name\"` was loaded.\n /// let loaded = metadata.contains_template(\"name\");\n /// }\n /// ```\n pub fn contains_template(&self, name: &str) -> bool {\n self.0.context().templates.contains_key(name)\n }\n\n /// Returns `true` if template reloading is enabled.\n ///\n /// # Example\n ///\n /// ```rust\n /// # #[macro_use] extern crate rocket;\n /// # extern crate rocket_dyn_templates;\n /// #\n /// use rocket_dyn_templates::Metadata;\n ///\n /// #[get(\"/\")]\n /// fn handler(metadata: Metadata) {\n /// // Returns `true` if template reloading is enabled.\n /// let reloading = metadata.reloading();\n /// }\n /// ```\n pub fn reloading(&self) -> bool {\n self.0.is_reloading()\n }\n\n /// Directly render the template named `name` with the context `context`\n /// into a `String`. Also returns the template's detected `ContentType`. See\n /// [`Template::render()`] for more details on rendering.\n ///\n /// # Examples\n ///\n /// ```rust\n /// # #[macro_use] extern crate rocket;\n /// use rocket::http::ContentType;\n /// use rocket_dyn_templates::{Metadata, Template, context};\n ///\n /// #[get(\"/\")]\n /// fn send_email(metadata: Metadata) -> Option<()> {\n /// let (mime, string) = metadata.render(\"email\", context! {\n /// field: \"Hello, world!\"\n /// })?;\n ///\n /// # /*\n /// send_email(mime, string).await?;\n /// # */\n /// Some(())\n /// }\n ///\n /// #[get(\"/\")]\n /// fn raw_render(metadata: Metadata) -> Option<(ContentType, String)> {\n /// metadata.render(\"index\", context! { field: \"Hello, world!\" })\n /// }\n ///\n /// // Prefer the following, however, which is nearly identical but pithier:\n ///\n /// #[get(\"/\")]\n /// fn render() -> Template {\n /// Template::render(\"index\", context! { field: \"Hello, world!\" })\n /// }\n /// ```\n pub fn render(&self, name: S, context: C) -> Option<(ContentType, String)>\n where S: Into>, C: Serialize\n {\n Template::render(name.into(), context).finalize(&self.0.context()).ok()\n }\n}\n\nimpl fmt::Debug for Metadata<'_> {\n fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n f.debug_map()\n .entries(&self.0.context().templates)\n .finish()\n }\n}\n\nimpl Sentinel for Metadata<'_> {\n fn abort(rocket: &Rocket) -> bool {\n if rocket.state::().is_none() {\n error!(\n \"uninitialized template context: missing `Template::fairing()`.\\n\\\n To use templates, you must attach `Template::fairing()`.\"\n );\n\n return true;\n }\n\n false\n }\n}\n\n/// Retrieves the template metadata. If a template fairing hasn't been attached,\n/// an error is printed and an empty `Err` with status `InternalServerError`\n/// (`500`) is returned.\n#[rocket::async_trait]\nimpl<'r> FromRequest<'r> for Metadata<'r> {\n type Error = ();\n\n async fn from_request(request: &'r Request<'_>) -> request::Outcome {\n request.rocket().state::()\n .map(|cm| request::Outcome::Success(Metadata(cm)))\n .unwrap_or_else(|| {\n error!(\n \"uninitialized template context: missing `Template::fairing()`.\\n\\\n To use templates, you must attach `Template::fairing()`.\"\n );\n\n request::Outcome::Error((Status::InternalServerError, ()))\n })\n }\n}\n" }, { "path": "contrib/dyn_templates/src/template.rs", "content": "use std::borrow::Cow;\nuse std::path::PathBuf;\n\nuse rocket::{Rocket, Orbit, Ignite, Sentinel};\nuse rocket::request::Request;\nuse rocket::fairing::Fairing;\nuse rocket::response::{self, Responder};\nuse rocket::http::{ContentType, Status};\nuse rocket::figment::{value::Value, error::Error};\nuse rocket::trace::Trace;\nuse rocket::serde::Serialize;\n\nuse crate::Engines;\nuse crate::fairing::TemplateFairing;\nuse crate::context::{Context, ContextManager};\n\npub(crate) const DEFAULT_TEMPLATE_DIR: &str = \"templates\";\n\n/// Responder that renders a dynamic template.\n///\n/// `Template` serves as a _proxy_ type for rendering a template and _does not_\n/// contain the rendered template itself. The template is lazily rendered, at\n/// response time. To render a template greedily, use [`Template::show()`].\n///\n/// See the [crate root](crate) for usage details.\n#[derive(Debug)]\npub struct Template {\n name: Cow<'static, str>,\n value: Result,\n}\n\n#[derive(Debug)]\npub(crate) struct TemplateInfo {\n /// The complete path, including `template_dir`, to this template, if any.\n pub(crate) path: Option,\n /// The extension for the engine of this template.\n pub(crate) engine_ext: &'static str,\n /// The extension before the engine extension in the template, if any.\n pub(crate) data_type: ContentType\n}\n\nimpl Template {\n /// Returns a fairing that initializes and maintains templating state.\n ///\n /// This fairing, or the one returned by [`Template::custom()`], _must_ be\n /// attached to any `Rocket` instance that wishes to render templates.\n /// Failure to attach this fairing will result in a \"Uninitialized template\n /// context: missing fairing.\" error message when a template is attempted to\n /// be rendered.\n ///\n /// If you wish to customize the internal templating engines, use\n /// [`Template::custom()`] instead.\n ///\n /// # Example\n ///\n /// To attach this fairing, simple call `attach` on the application's\n /// `Rocket` instance with `Template::fairing()`:\n ///\n /// ```rust\n /// extern crate rocket;\n /// extern crate rocket_dyn_templates;\n ///\n /// use rocket_dyn_templates::Template;\n ///\n /// fn main() {\n /// rocket::build()\n /// // ...\n /// .attach(Template::fairing())\n /// // ...\n /// # ;\n /// }\n /// ```\n pub fn fairing() -> impl Fairing {\n Template::custom(|_| {})\n }\n\n /// Returns a fairing that initializes and maintains templating state.\n ///\n /// Unlike [`Template::fairing()`], this method allows you to configure\n /// templating engines via the function `f`. Note that only the enabled\n /// templating engines will be accessible from the `Engines` type.\n ///\n /// This method does not allow the function `f` to fail. If `f` is fallible,\n /// use [`Template::try_custom()`] instead.\n ///\n /// # Example\n ///\n /// ```rust\n /// extern crate rocket;\n /// extern crate rocket_dyn_templates;\n ///\n /// use rocket_dyn_templates::Template;\n ///\n /// fn main() {\n /// rocket::build()\n /// // ...\n /// .attach(Template::custom(|engines| {\n /// // engines.handlebars.register_helper ...\n /// }))\n /// // ...\n /// # ;\n /// }\n /// ```\n pub fn custom(f: F) -> impl Fairing\n where F: Fn(&mut Engines)\n {\n Self::try_custom(move |engines| { f(engines); Ok(()) })\n }\n\n /// Returns a fairing that initializes and maintains templating state.\n ///\n /// This variant of [`Template::custom()`] allows a fallible `f`. If `f`\n /// returns an error during initialization, it will cancel the launch. If\n /// `f` returns an error during template reloading (in debug mode), then the\n /// newly-reloaded templates are discarded.\n ///\n /// # Example\n ///\n /// ```rust\n /// extern crate rocket;\n /// extern crate rocket_dyn_templates;\n ///\n /// use rocket_dyn_templates::Template;\n ///\n /// fn main() {\n /// rocket::build()\n /// // ...\n /// .attach(Template::try_custom(|engines| {\n /// // engines.handlebars.register_helper ...\n /// Ok(())\n /// }))\n /// // ...\n /// # ;\n /// }\n /// ```\n pub fn try_custom(f: F) -> impl Fairing\n where F: Fn(&mut Engines) -> Result<(), Box>\n {\n TemplateFairing { callback: Box::new(f) }\n }\n\n /// Render the template named `name` with the context `context`. The\n /// `context` is typically created using the [`context!()`](crate::context!)\n /// macro, but it can be of any type that implements `Serialize`, such as\n /// `HashMap` or a custom `struct`.\n ///\n /// To render a template directly into a string, use\n /// [`Metadata::render()`](crate::Metadata::render()).\n ///\n /// # Examples\n ///\n /// Using the `context` macro:\n ///\n /// ```rust\n /// use rocket_dyn_templates::{Template, context};\n ///\n /// let template = Template::render(\"index\", context! {\n /// foo: \"Hello, world!\",\n /// });\n /// ```\n ///\n /// Using a `HashMap` as the context:\n ///\n /// ```rust\n /// use std::collections::HashMap;\n /// use rocket_dyn_templates::Template;\n ///\n /// // Create a `context` from a `HashMap`.\n /// let mut context = HashMap::new();\n /// context.insert(\"foo\", \"Hello, world!\");\n ///\n /// let template = Template::render(\"index\", context);\n /// ```\n #[inline]\n pub fn render(name: S, context: C) -> Template\n where S: Into>, C: Serialize\n {\n Template {\n name: name.into(),\n value: Value::serialize(context),\n }\n }\n\n /// Render the template named `name` with the context `context` into a\n /// `String`. This method should **not** be used in any running Rocket\n /// application. This method should only be used during testing to validate\n /// `Template` responses. For other uses, use [`render()`](#method.render)\n /// instead.\n ///\n /// The `context` can be of any type that implements `Serialize`. This is\n /// typically a `HashMap` or a custom `struct`.\n ///\n /// Returns `Some` if the template could be rendered. Otherwise, returns\n /// `None`. If rendering fails, error output is printed to the console.\n /// `None` is also returned if a `Template` fairing has not been attached.\n ///\n /// # Example\n ///\n /// ```rust,no_run\n /// # extern crate rocket;\n /// # extern crate rocket_dyn_templates;\n /// use std::collections::HashMap;\n ///\n /// use rocket_dyn_templates::Template;\n /// use rocket::local::blocking::Client;\n ///\n /// fn main() {\n /// let rocket = rocket::build().attach(Template::fairing());\n /// let client = Client::untracked(rocket).expect(\"valid rocket\");\n ///\n /// // Create a `context`. Here, just an empty `HashMap`.\n /// let mut context = HashMap::new();\n /// # context.insert(\"test\", \"test\");\n /// let template = Template::show(client.rocket(), \"index\", context);\n /// }\n /// ```\n #[inline]\n pub fn show(rocket: &Rocket, name: S, context: C) -> Option\n where S: Into>, C: Serialize\n {\n let ctxt = rocket.state::()\n .map(ContextManager::context)\n .or_else(|| {\n error!(\"Uninitialized template context: missing fairing.\\n\\\n To use templates, you must attach `Template::fairing()`.\\n\\\n See the `Template` documentation for more information.\");\n\n None\n })?;\n\n Template::render(name, context).finalize(&ctxt).ok().map(|v| v.1)\n }\n\n /// Actually render this template given a template context. This method is\n /// called by the `Template` `Responder` implementation as well as\n /// `Template::show()`.\n #[inline(always)]\n pub(crate) fn finalize(self, ctxt: &Context) -> Result<(ContentType, String), Status> {\n let template = &*self.name;\n let info = ctxt.templates.get(template).ok_or_else(|| {\n let ts: Vec<_> = ctxt.templates.keys().map(|s| s.as_str()).collect();\n error!(\n %template, search_path = %ctxt.root.display(), known_templates = ?ts,\n \"requested template not found\"\n );\n\n Status::InternalServerError\n })?;\n\n let value = self.value.map_err(|e| {\n span_error!(\"templating\", \"template context failed to serialize\" => e.trace_error());\n Status::InternalServerError\n })?;\n\n let string = ctxt.engines.render(template, info, value).ok_or_else(|| {\n error!(template, \"template failed to render\");\n Status::InternalServerError\n })?;\n\n Ok((info.data_type.clone(), string))\n }\n}\n\n/// Returns a response with the Content-Type derived from the template's\n/// extension and a fixed-size body containing the rendered template. If\n/// rendering fails, an `Err` of `Status::InternalServerError` is returned.\nimpl<'r> Responder<'r, 'static> for Template {\n fn respond_to(self, req: &'r Request<'_>) -> response::Result<'static> {\n let ctxt = req.rocket()\n .state::()\n .ok_or_else(|| {\n error!(\n \"uninitialized template context: missing `Template::fairing()`.\\n\\\n To use templates, you must attach `Template::fairing()`.\"\n );\n\n Status::InternalServerError\n })?;\n\n self.finalize(&ctxt.context())?.respond_to(req)\n }\n}\n\nimpl Sentinel for Template {\n fn abort(rocket: &Rocket) -> bool {\n if rocket.state::().is_none() {\n error!(\n \"Missing `Template::fairing()`.\\n\\\n To use templates, you must attach `Template::fairing()`.\"\n );\n\n return true;\n }\n\n false\n }\n}\n\n/// A macro to easily create a template rendering context.\n///\n/// Invocations of this macro expand to a value of an anonymous type which\n/// implements [`Serialize`]. Fields can be literal expressions or variables\n/// captured from a surrounding scope, as long as all fields implement\n/// `Serialize`.\n///\n/// # Examples\n///\n/// The following code:\n///\n/// ```rust\n/// # #[macro_use] extern crate rocket;\n/// # use rocket_dyn_templates::{Template, context};\n/// #[get(\"/\")]\n/// fn render_index(foo: u64) -> Template {\n/// Template::render(\"index\", context! {\n/// // Note that shorthand field syntax is supported.\n/// // This is equivalent to `foo: foo,`\n/// foo,\n/// bar: \"Hello world\",\n/// })\n/// }\n/// ```\n///\n/// is equivalent to the following, but without the need to manually define an\n/// `IndexContext` struct:\n///\n/// ```rust\n/// # use rocket_dyn_templates::Template;\n/// # use rocket::serde::Serialize;\n/// # use rocket::get;\n/// #[derive(Serialize)]\n/// # #[serde(crate = \"rocket::serde\")]\n/// struct IndexContext<'a> {\n/// foo: u64,\n/// bar: &'a str,\n/// }\n///\n/// #[get(\"/\")]\n/// fn render_index(foo: u64) -> Template {\n/// Template::render(\"index\", IndexContext {\n/// foo,\n/// bar: \"Hello world\",\n/// })\n/// }\n/// ```\n///\n/// ## Nesting\n///\n/// Nested objects can be created by nesting calls to `context!`:\n///\n/// ```rust\n/// # use rocket_dyn_templates::context;\n/// # fn main() {\n/// let ctx = context! {\n/// planet: \"Earth\",\n/// info: context! {\n/// mass: 5.97e24,\n/// radius: \"6371 km\",\n/// moons: 1,\n/// },\n/// };\n/// # }\n/// ```\n#[macro_export]\nmacro_rules! context {\n ($($key:ident $(: $value:expr)?),*$(,)?) => {{\n use $crate::serde::ser::{Serialize, Serializer, SerializeMap};\n use ::std::fmt::{Debug, Formatter};\n use ::std::result::Result;\n\n #[allow(non_camel_case_types)]\n struct ContextMacroCtxObject<$($key: Serialize),*> {\n $($key: $key),*\n }\n\n #[allow(non_camel_case_types)]\n impl<$($key: Serialize),*> Serialize for ContextMacroCtxObject<$($key),*> {\n fn serialize(&self, serializer: S) -> Result\n where S: Serializer,\n {\n let mut map = serializer.serialize_map(None)?;\n $(map.serialize_entry(stringify!($key), &self.$key)?;)*\n map.end()\n }\n }\n\n #[allow(non_camel_case_types)]\n impl<$($key: Debug + Serialize),*> Debug for ContextMacroCtxObject<$($key),*> {\n fn fmt(&self, f: &mut Formatter<'_>) -> ::std::fmt::Result {\n f.debug_struct(\"context!\")\n $(.field(stringify!($key), &self.$key))*\n .finish()\n }\n }\n\n ContextMacroCtxObject {\n $($key $(: $value)?),*\n }\n }};\n}\n" }, { "path": "contrib/dyn_templates/tests/templates/hbs/common/footer.html.hbs", "content": "Done.\n" }, { "path": "contrib/dyn_templates/tests/templates/hbs/common/header.html.hbs", "content": "Hello {{ title }}!\n" }, { "path": "contrib/dyn_templates/tests/templates/hbs/reload.txt.hbs", "content": "initial" }, { "path": "contrib/dyn_templates/tests/templates/hbs/test.html.hbs", "content": "{{> hbs/common/header }}\n

{{ content }}
\n{{> hbs/common/footer }}\n" }, { "path": "contrib/dyn_templates/tests/templates/j2/[test]/html_test.html.j2", "content": "{% extends \"j2/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates/j2/base.txt.j2", "content": "{% block head %}\nh_start\ntitle: {% block title %}{% endblock title %}\nh_end\n{% endblock head %}\n{% block content %}{% endblock content %}\n{% block footer %}foot{% endblock footer %}\n" }, { "path": "contrib/dyn_templates/tests/templates/j2/html_test.html.j2", "content": "{% extends \"j2/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates/j2/txt_test.txt.j2", "content": "{% extends \"j2/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates/tera/[test]/html_test.html.tera", "content": "{% extends \"tera/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates/tera/base.txt.tera", "content": "{% block head %}\nh_start\ntitle: {% block title %}{% endblock title %}\nh_end\n{% endblock head %}\n{% block content %}{% endblock content %}\n{% block footer %}foot{% endblock footer -%}\n" }, { "path": "contrib/dyn_templates/tests/templates/tera/html_test.html.tera", "content": "{% extends \"tera/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates/tera/txt_test.txt.tera", "content": "{% extends \"tera/base\" %}\n{% block title %}{{ title }}{% endblock title %}\n{% block content %}\n{{ content }}\n{% endblock content %}\n" }, { "path": "contrib/dyn_templates/tests/templates.rs", "content": "#[macro_use] extern crate rocket;\n\nuse std::path::{Path, PathBuf};\n\nuse rocket::{Rocket, Build};\nuse rocket::config::Config;\nuse rocket::figment::value::Value;\nuse rocket::serde::{Serialize, Deserialize};\nuse rocket_dyn_templates::{Template, Metadata, context};\n\n#[get(\"//\")]\nfn template_check(md: Metadata<'_>, engine: &str, name: &str) -> Option<()> {\n md.contains_template(&format!(\"{}/{}\", engine, name)).then(|| ())\n}\n\n#[get(\"/is_reloading\")]\nfn is_reloading(md: Metadata<'_>) -> Option<()> {\n if md.reloading() { Some(()) } else { None }\n}\n\nfn template_root() -> PathBuf {\n Path::new(env!(\"CARGO_MANIFEST_DIR\")).join(\"tests\").join(\"templates\")\n}\n\nfn rocket() -> Rocket {\n rocket::custom(Config::figment().merge((\"template_dir\", template_root())))\n .attach(Template::fairing())\n .mount(\"/\", routes![template_check, is_reloading])\n}\n\n#[test]\nfn test_callback_error() {\n use rocket::{local::blocking::Client, error::ErrorKind::FailedFairings};\n\n let rocket = rocket::build().attach(Template::try_custom(|_| {\n Err(\"error reloading templates!\".into())\n }));\n\n let error = Client::debug(rocket).expect_err(\"client failure\");\n match error.kind() {\n FailedFairings(failures) => assert_eq!(failures[0].name, \"Templating\"),\n _ => panic!(\"Wrong kind of launch error\"),\n }\n}\n\n#[test]\nfn test_sentinel() {\n use rocket::{local::blocking::Client, error::ErrorKind::SentinelAborts};\n\n let err = Client::debug_with(routes![is_reloading]).unwrap_err();\n assert!(matches!(err.kind(), SentinelAborts(vec) if vec.len() == 1));\n\n let err = Client::debug_with(routes![is_reloading, template_check]).unwrap_err();\n assert!(matches!(err.kind(), SentinelAborts(vec) if vec.len() == 2));\n\n #[get(\"/\")]\n fn return_template() -> Template {\n Template::render(\"foo\", ())\n }\n\n let err = Client::debug_with(routes![return_template]).unwrap_err();\n assert!(matches!(err.kind(), SentinelAborts(vec) if vec.len() == 1));\n\n #[get(\"/\")]\n fn return_opt_template() -> Option