refactor!: extract framework core to cot-core

[seqre]

This PR attempts to extract the core functionality of the framework to separate crate to speed up compilation among other reasons.

The modules fully/partially moved:

• basic Cot types
• body
• error
• headers
• html
• json
• response
• request
• middleware
• handler

I think moving router would be valid move as well, but in the current format it's too intertwined with OpenAPI functionality (that we don't want to pull into core) that it can be done at a later time.

With cot-core being a separate crate, the following items had to become public:

• cot_core::error::backtrace - needed for ErrorPage
• cot_core::error::error_impl::* - to allow implementing of errors in cot
• Error.backtrace() - needed for supplying error backtrace in ErrorPageTemplateBuilder
• Backtrace.frames() - needed for the Template derive for ErrorPageTemplate (used in error.html template)
• StackFrame.symbol_name() - as above
• StackFrame.location() - as above
• StackFrame - as above
• Body.axum() - needed for request_axum_to_cot in project.rs
• InvalidContentType
• AppName
• RouteName
• BoxRequestHandler - used in openapi.rs and router.rs
• into_box_request_handler - used in method.rs and router.rs

Stayed private with following gotchas:

• NotFound.router() - removed deprecated NotFound constructor methods from Error

[seqre]

The nightly error should be fixed by rust-lang/rust#150939

[m4tx]

Looks nice, and seems like it lays a solid foundation for our eventual extraction of the ORM to a separate crate!

I've tried to generate the docs with just docs and it seems like there's a ton of warnings coming from cot-core (outside of missing examples, which are expected) - please make sure these are fixed before we consider merging this.

[m4tx]

Perhaps it makes sense to change this enum variant to be a struct variant with named field rather than enum variant? After all, we might (however unlikely) want to add some more fields to it, at which point we'll probably need to add some naming so it's clear what they do. Think "future-proofing the APIs".

[seqre]

I can do it, but I doubt we'll want to expand that variant, so there's little to it

[codecov]

Codecov Report

❌ Patch coverage is 93.60902% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-core/src/request/extractors.rs	94.11%	3 Missing and 4 partials ⚠️
cot-core/src/middleware.rs	85.71%	6 Missing ⚠️
cot/src/request/extractors.rs	86.66%	2 Missing ⚠️
cot-core/src/request.rs	98.21%	0 Missing and 1 partial ⚠️
cot/src/error_page.rs	0.00%	1 Missing ⚠️

Flag	Coverage Δ
rust	90.41% <93.60%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot-core/src/body.rs	84.89% <100.00%> (ø)
cot-core/src/error/backtrace.rs	96.82% <100.00%> (ø)
cot-core/src/error/error_impl.rs	90.13% <100.00%> (ø)
cot-core/src/error/method_not_allowed.rs	100.00% <ø> (ø)
cot-core/src/error/uncaught_panic.rs	75.00% <ø> (ø)
cot-core/src/handler.rs	78.26% <100.00%> (ø)
cot-core/src/html.rs	97.44% <ø> (ø)
cot-core/src/request/path_params_deserializer.rs	63.49% <ø> (ø)
cot-core/src/response.rs	96.66% <ø> (ø)
cot-core/src/response/into_response.rs	99.26% <100.00%> (ø)
... and 26 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 47 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[m4tx]

We need to make sure this change doesn't affect the user's experience. In particular, the docs must work as before, and we cannot expose any internal APIs (as this could cause some breakages in the long run).

[m4tx]

These links (and probably most others) don't work when you look at the docs from the cot crate. Is there really no way to avoid specifying exact paths? How do other projects handle this? I can see some discussion on this, e.g. rust-lang/docs.rs#1588

[seqre]

This might be a skill issue on my side, but whatever I tried, I could not make it work properly. The issue I think is that cot is not a dependency of cot_core, so rustdoc has issues with linking to it. I attempted using unstable rustdoc-map feature with doc.extern-map.registries, but it did not seem to work. We could always just put there normal crates.io links to latest, but I don't like it. Could you assist?

[m4tx]

How about we move these docs to the main crate? If we mention high-level concepts in this doc, I think it's okay to move the docs to the high-level crate.

The problematic one is the new_redirect method inside the ResponseExt trait. I'm honestly thinking that this should be a separate struct (probably defined in cot) rather than a method in an extension trait, as it would be more consistent with the rest of our APIs now, and also would make the core types less "special". Basically instead of Response::new_redirect("link") we should have Redirect::new("link"). What do you think?

[m4tx]

This is an implementation detail and cannot be exposed to users. The CotBacktrace struct is (rightly) not even reexported in Cot.

[seqre]

It's problematic, it has to be public so that the error page can use it to show backtrace properly. The easiest solution would be to pull that to cot, but then we would have to pull Error as well and it's impossible as it's used in cot_core. Alternatively, we could pull ErrorPage to cot_core, but it's not really core and it's specific to cot. Thoughts?

[m4tx]

I think the error struct should be kept in the core crate. I can see several approaches here:

1. #[doc(hidden)] - the easiest way. Perhaps it's good enough (I think some popular crates such as tokio and serde do use it), but it doesn't really stop the users from calling the method.
2. Defining an extension trait (similar to ResponseExt, for example), and implementing it for the Error type. The extension trait is then public in cot-core, but not reexported in cot. This way the method will be invisible to the normal users, but still accessible if you use cot-core directly.
3. Sort of similar to the one above: defining an access token. The code explains it all:

mod private {
    pub struct Token;
}

pub struct MyStruct;

impl MyStruct {
    pub fn restricted_method(&self, _: private::Token) {
        println!("Restricted!");
    }
}

#[doc(hidden)]
pub fn get_token() -> private::Token {
    private::Token
}

I'll let you pick the favorite one for the job.