feat!: support for rolling back migrations

[ElijahAhianyo]

Related issue or discussion

fixes #547

Description

This allows rolling back migrations to the specified migration file.

Assuming the project has the following migration files in its migration dir:

├── migrations
 │   └── m_0001_initial.rs
 |   └── m_0002_second.rs

./target/debug/foo migration rollback m_0001_initial

The above command will roll back(unapply) the m_0002_second file, leaving m_0001_initial applied.
Alternatively, the migration file number can be used for convenience:

./target/debug/foo migration rollback 0001

Migrations are currently tied to a crate(the crate name is used), which means rolling back a migration in a project that imports apps from external crates will implicitly (and only) rollback migrations in the current project/crate. This might change when support for workspaces is added

As a bonus, this PR also adds CLI Group tasks as a means to group nested related subcommands under a parent subcommand:

Eg.

     use async_trait::async_trait;
     use clap::{ArgMatches, Command};
     use cot::cli::{Cli, CliTask, CliTaskGroup};
     use cot::project::WithConfig;
     use cot::{Bootstrapper, Project};
    
     struct Frobnicate;
    
     #[async_trait(?Send)]
     impl CliTask for Frobnicate {
         fn subcommand(&self) -> Command {
             Command::new("frobnicate")
                  .about("Test frobnicate command")

         }
    
         async fn execute(
             &mut self,
             _matches: &ArgMatches,
             _bootstrapper: Bootstrapper<WithConfig>,
         ) -> cot::Result<()> {
             println!("Frobnicating...");
    
             Ok(())
         }
     }
    
     struct MyProject;
     impl Project for MyProject {
         fn register_tasks(&self, cli: &mut Cli) {
             let mut group_command = CliTaskGroup::new("foo").about("Foo related commands");
             group_command.add_task(Frobnicate);
             cli.add_task(group_command);
        }
   }

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / cleanup
• Performance improvement
• Other (describe above)

[github-actions]

Bencher Report

Project	cot
Branch	elijah/migrations-rollback
Testbed	github-ubuntu-latest

🚨 1 Alert

Benchmark	Measure Units	View	Benchmark Result (Result Δ%)	Upper Boundary (Limit %)
empty_router/empty_router	Latency milliseconds (ms)	📈 plot 🚷 threshold 🚨 alert (🔔)	13.78 ms (+87.82%) Baseline: 7.34 ms	12.81 ms (107.61%)

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold 🚨 view alert (🔔)	13,783.00 µs (+87.82%) Baseline: 7,338.41 µs	12,807.92 µs (107.61%)
json_api/json_api	📈 view plot 🚷 view threshold	1,120.60 µs (+4.00%) Baseline: 1,077.50 µs	1,368.44 µs (81.89%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	1,044.90 µs (+4.06%) Baseline: 1,004.10 µs	1,245.23 µs (83.91%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	994.30 µs (+2.81%) Baseline: 967.14 µs	1,208.85 µs (82.25%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17,179.00 µs (-1.03%) Baseline: 17,357.78 µs	21,685.90 µs (79.22%)

🐰 View full continuous benchmarking report in Bencher

[codecov]

Codecov Report

❌ Patch coverage is 88.43188% with 45 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot/src/db/migrations.rs	85.22%	21 Missing and 22 partials ⚠️
cot/src/cli.rs	97.70%	2 Missing ⚠️

Flag	Coverage Δ
rust	90.22% <88.43%> (-0.03%)	⬇️

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

Files with missing lines	Coverage Δ
cot/src/db/migrations/sorter.rs	93.59% <100.00%> (+0.12%)	⬆️
cot/src/utils/graph.rs	98.76% <100.00%> (+0.04%)	⬆️
cot/src/cli.rs	87.33% <97.70%> (+4.07%)	⬆️
cot/src/db/migrations.rs	84.20% <85.22%> (+0.72%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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

[m4tx]

Looks like a solid start, but we need more work on this before it can be merged.

[m4tx]

I believe a few features would make it much more useful:

1. A subcommand that would list all available migrations
2. A dry run mode to see which migrations would actually be rolled back
3. Actual log lines being displayed. cot-cli just eprintlns the info when executing migration make, which I think we could replicate here.

[ElijahAhianyo]

For a subcommand to list all available migrations, I believe we already have that in cot-cli via cot migration list and I dont think we should duplicate that in cot crate. Perhaps this is where #587 can come in handy

[m4tx]

Ah, fair, I forgot about this. In that case yes, I think that should suffice for now.

For the future, though, (outside of this PR) maybe it would be useful to have a separate command for listing applied and pending migrations (which would have to be implemented outside of cot-cli I believe).

[seqre]

Apart from @m4tx comments, please add snapshot tests for the new commands

[m4tx]

I'm wondering if it would make sense to take all the #[doc(hidden)] stuff and just move it into another crate. This shouldn't happen in this PR anyway, but this is just something that maybe we should do at some point.

[ElijahAhianyo]

Do you think the cot-core crate is a good place to move these?

[m4tx]

I'm not sure, the idea behind cot-core is to only contain the bare, rock-solid minimum required to serve the core functionality (so mostly just HTTP stuff) with minimal number of dependencies. I'm not sure if adding pretty printing there (which is quite a high-level functionality) belongs there. We don't necessarily need to care about this right now, though.