From d79237b10300536a8a616e529bdff4b615c7fc82 Mon Sep 17 00:00:00 2001 From: Lucas Colombo Date: Fri, 21 Jun 2024 16:36:42 -0300 Subject: [PATCH] =?UTF-8?q?feat:=20=E2=9C=A8=20don't=20connect=20if=20alre?= =?UTF-8?q?ady=20connected=20or=20connecting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/img/doc-title-rustler.svg | 9 ++-- README.md | 21 +++------- lib/README.md | 38 +++++++++++++++++ lib/lib.rs | 2 + lib/rustlers/README.md | 70 ++++++++++++++++++------------- lib/rustlers/mod.rs | 4 ++ lib/rustlers/rustler.rs | 6 +-- 7 files changed, 99 insertions(+), 51 deletions(-) create mode 100644 lib/README.md diff --git a/.github/img/doc-title-rustler.svg b/.github/img/doc-title-rustler.svg index a137af1..5490b7a 100644 --- a/.github/img/doc-title-rustler.svg +++ b/.github/img/doc-title-rustler.svg @@ -1,11 +1,12 @@ - + - - - + + + + \ No newline at end of file diff --git a/README.md b/README.md index e51ef05..0a938f4 100644 --- a/README.md +++ b/README.md @@ -20,26 +20,15 @@ Also, this library is built using the `Rust` programming language... so, **_rust ## What this library includes -This library defines the core functionality for a `rustler`. It includes the following: - -- A [`Rustler`](./lib/rustlers/rustler.rs) trait that defines the core functionality for a `rustler`. -- A [`RustlersSvc`](./lib/rustlers/svc.rs) which orchestrates the `rustlers` at runtime, scheduling them to scrape stock pricing data between market hours. - -More info [here](./lib/rustlers/README.md). - -Apart from the above, this library also defines: - -- a [database schema](./lib/entities/orm/) for storing market hours, which is used by the `RustlersSvc` to schedule the `rustlers`. -- initial [database migrations](./lib/entities/migration) to create the schema. -- a [grpc server](./lib/grpc/) to interact with the rustlers database. -- unimplemented a [websocket gateway server](./lib/socket/) to stream stock pricing data to subscribed clients +See [here](./lib/rustlers/README.md). > [!NOTE] > -> This library defines a _rustler_ as a service that scrapes stock pricing data for a -> particular market. +> This library defines a _rustler_ as a service that scrapes stock pricing data for a particular +> market. > -> Although this library contains the core and abstract functionality for the rustlers, it doesn't include any concrete implementation for them. +> Although this library contains the core and abstract functionality for the rustlers, it doesn't +> include any concrete implementation for them. > > Actual concrete implementations for each market cannot be published for many reasons. diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000..28db83c --- /dev/null +++ b/lib/README.md @@ -0,0 +1,38 @@ +

+ +
+
+ +

+๐ซ๐ฎ๐ฌ๐ญ๐ฅ๐ž๐ซ โซฎ ๐œ๐จ๐ซ๐ž is a library that contains the core functionality for `rustler`, a web scraping service +that scrapes several stock market providers for stock pricing data. It is built using the +Rust programming language. +

+ +
+
+ +## Why "rustler" + +A `rustler` is a person who steals live**_stock_**. Well, this library is a service that collects +_stock_ market data from the internet. So, it's a "_rustler_" for stock market data. + +Also, this library is built using the `Rust` programming language... so, __rust__-ler ๐Ÿ˜Š + +## What this library includes + +This library defines the core functionality for a `rustler`. It includes the following: + +- A [`rustlers::Rustler`] trait that defines the core functionality for a `rustler`. +- A [`rustlers::svc::RustlersSvc`] which orchestrates the `rustlers` at runtime, scheduling them to scrape stock pricing data between market hours. + +More info [here](rustlers). + +Apart from the above, this library also defines: + +- a [database schema](entities) for storing market hours, which is used by the `RustlersSvc` to schedule the `rustlers`. +- initial [database migrations](entities/migration) to create the schema. +- a [grpc server](grpc) to interact with the rustlers database. +- a [websocket gateway server](socket) to stream stock pricing data to subscribed clients + + diff --git a/lib/lib.rs b/lib/lib.rs index e714b26..9bf4553 100644 --- a/lib/lib.rs +++ b/lib/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("README.md")] + pub mod bus; pub mod entities; pub mod grpc; diff --git a/lib/rustlers/README.md b/lib/rustlers/README.md index fe9a2a9..6662747 100644 --- a/lib/rustlers/README.md +++ b/lib/rustlers/README.md @@ -1,44 +1,56 @@ -

+



## `rustler.rs` -Contains the `rustler!` macro, which is used to define a `Rustler`. +Contains the `rustler!` macro, which is used to define a [`Rustler`]. -`Rustler` is a trait that extends the `RustlerAccessor` trait. +[`Rustler`] is a trait that extends the [`RustlerAccessor`] trait. Together, they define the interface and the common functionalities for all Rustlers. -### The `RustlerAccessor` trait +### The [`RustlerAccessor`] trait -The `RustlerAccessor` trait defines the interface for accessing the Rustler's data (`getters` and `setters` that all Rustlers must implement). +The [`RustlerAccessor`] trait defines the interface for accessing the Rustler's data (`getters` and +`setters` that all Rustlers must implement). Some of the expected accessors are: - `status` and `set_status` - `tickers` and `set_tickers` - `msg_sender` and `set_msg_sender` -### The `Rustler` trait +### The [`Rustler`] trait -The `Rustler` trait extends the `RustlerAccessor` trait and defines the interface for common Rustler's functionalities: +The [`Rustler`] trait extends the [`RustlerAccessor`] trait and defines the interface for common +Rustler's functionalities: -- `start` the Rustler, calling abstract `connect` if the Rustler is set to connect on start +- [`Rustler::start`] the Rustler, calling abstract [`Rustler::connect`] if the Rustler is set to + connect on start - status change handling -- `add` new tickers to the Rustler (calling `on_add` at the end if tickers were added). Also calls `connect` if the Rustler is set to connect on add and the Rustler is not already connected -- `delete` tickers from the Rustler (calling `on_delete` at the end if tickers were deleted). Also calls `disconnect` if there are no more tickers in the Rustler. +- [`Rustler::add`] new tickers to the Rustler (calling [`Rustler::on_add`] at the end if tickers + were added). Also calls [`Rustler::connect`] if the Rustler is set to connect on add and the + Rustler is not already connected +- [`Rustler::delete`] tickers from the Rustler (calling [`Rustler::on_delete`] at the end if tickers + were deleted). Also calls [`Rustler::disconnect`] if there are no more tickers in the Rustler. -The `Rustler` trait also defines the following abstract methods that must be implemented by each `Rustler` implementation. +The [`Rustler`] trait also defines the following abstract methods that must be implemented by each +[`Rustler`] implementation. -- `connect` method that connects the Rustler to the data source -- `disconnect` method that disconnects the Rustler from the data source -- `on_add` method that is called when new tickers are added to the Rustler. This method is called when new tickers are added to the Rustler and must implement the logic to start tracking and rustling the new tickers. -- `on_delete` method that is called when tickers are deleted from the Rustler. This method is called when tickers are deleted from the Rustler and must implement the logic to stop tracking and rustling the deleted tickers. +- [`Rustler::connect`] method that connects the Rustler to the data source +- [`Rustler::disconnect`] method that disconnects the Rustler from the data source +- [`Rustler::on_add`] method that is called when new tickers are added to the Rustler. This method + is called when new tickers are added to the Rustler and must implement the logic to start tracking + and rustling the new tickers. +- `on_delete` method that is called when tickers are deleted from the Rustler. This method is called + when tickers are deleted from the Rustler and must implement the logic to stop tracking and + rustling the deleted tickers. ### The `rustler!` macro -The `rustler!` macro is used to define a `Rustler` and to automatically implement the `RustlerAccessor` trait. This adds the necessary fields and accessors to the struct. +The `rustler!` macro is used to define a [`Rustler`] and to automatically implement the +[`RustlerAccessor`] trait. This adds the necessary fields and accessors to the struct. **Example:** @@ -48,20 +60,21 @@ rustler! { } ``` -Now we have a `MyRustler` struct that implements the `RustlerAccessor` +Now we have a `MyRustler` struct that implements the [`RustlerAccessor`] trait and has all the necessary fields and accessors :) ## `rustlerjar.rs` -This files defines the `RustlerJar` struct. +This files defines the [`rustlerjar::RustlerJar`] struct. -A `RustlerJar` is a collection of `Rustler`s and their corresponding mappings to markets. Such mapping indicates which Rustler should be used for a given market. +A [`rustlerjar::RustlerJar`] is a collection of [`Rustler`]s and their corresponding mappings to markets. Such +mapping indicates which Rustler should be used for a given market. -It provides methods to retrieve Rustlers by `Market`. +It provides methods to retrieve Rustlers by [`crate::entities::market`]. ### The `rustlerjar!` macro -The `rustlerjar!` macro is used to create an instance of a `RustlerJar` on an easy way. +The `rustlerjar!` macro is used to create an instance of a [`rustlerjar::RustlerJar`] on an easy way. **Example:** @@ -74,22 +87,23 @@ let rustler_jar = rustlerjar! { let rustler = rustler_jar.get(&market); ``` -the `rustlerjar!` expects a mapping of **market names** pointing to **`Rustler` creation functions (constructors)** and will return a `RustlerJar` instance. +the `rustlerjar!` expects a mapping of **market names** pointing to **[`Rustler`] creation functions (constructors)** and will return a [`rustlerjar::RustlerJar`] instance. -Note: the `rustlerjar!` macro executes the `create` function for each `Rustler`, so in the example above, we assume that `BinaceRustler::create(url)` returns a function that creates a new instance of `BinanceRustler` and not an instance of `BinanceRustler`. +Note: the `rustlerjar!` macro executes the `create` function for each [`Rustler`], so in the example above, we assume that `BinaceRustler::create(url)` returns a function that creates a new instance of `BinanceRustler` and not an instance of `BinanceRustler`. ## `svc.rs` -Contains the `RustlersSvc` struct. +Contains the [`svc::RustlersSvc`] struct. -The `RustlersSvc` struct is a service that manages the execution of several `Rustler`s from a `RustlerJar`. +The [`svc::RustlersSvc`] struct is a service that manages the execution of several [`Rustler`]s from a `RustlerJar`. It is responsible for starting and stopping the Rustlers on the right schedule. It contains a `MarketService`, which connects to the database and is used to retrieve the markets (including their schedules) and their tickets. Then, for each market, it retrieves the corresponding Rustler from the `RustlerJar`, adds the tickers to the it, and starts it. -> [!NOTE] +> **NOTE** > -> unimplemented +> unimplemented > -> Although it's not yet implemented, the `RustlersSvc` will also be responsible for adding and deleting tickers and rustlers at runtime. \ No newline at end of file +> Although it's not yet implemented, the [`svc::RustlersSvc`] will also be responsible for adding and +> deleting tickers and rustlers at runtime. \ No newline at end of file diff --git a/lib/rustlers/mod.rs b/lib/rustlers/mod.rs index 3e46eaf..d18ab12 100644 --- a/lib/rustlers/mod.rs +++ b/lib/rustlers/mod.rs @@ -1,3 +1,7 @@ +//! The rustlers module defines [`Rustler`], a trait that allows rustling data from a source. + +#![doc = include_str!("README.md")] + mod rustler; pub mod rustlerjar; diff --git a/lib/rustlers/rustler.rs b/lib/rustlers/rustler.rs index 68ca85d..f8f0473 100644 --- a/lib/rustlers/rustler.rs +++ b/lib/rustlers/rustler.rs @@ -357,7 +357,7 @@ pub trait Rustler: RustlerAccessor + Send + Sync { /// ๐ŸŽ ยป starts the rustler async fn start(&mut self) -> Result<()> { let opts = self.opts(); - if opts.connect_on_start { + if opts.connect_on_start && !self.is_connected_or_connecting() { self.connect().await?; } Ok(()) @@ -400,7 +400,7 @@ pub trait Rustler: RustlerAccessor + Send + Sync { if self.opts().connect_on_add { // if disconnected, then connect the rustler - if self.status() == &RustlerStatus::Disconnected { + if !self.is_connected_or_connecting() { self.connect().await?; } } @@ -433,7 +433,7 @@ pub trait Rustler: RustlerAccessor + Send + Sync { // if after deleting the tickers the tickers map is // empty, disconnect the rustler - if tickers.is_empty() { + if tickers.is_empty() && !self.is_disconnected_or_disconnecting() { self.disconnect().await?; }