hncli Rust Architecture Overview

/// An `Item` in the HackerNews API covers everything except `User`s.
///
/// Used for deserialization, with dispatch on `type`.
#[derive(Clone, Debug, Deserialize)]
#[serde(tag = "type")]
#[serde(rename_all = "lowercase")]
pub enum HnItem {
    Story(HnStory),
    Comment(HnComment),
    Job(HnJob),
    // ...
}

pub struct UserInterface {
    terminal: TerminalUi, // main tui-rs structure using crossterm to render (custom) widgets in the terminal
    client: HnClient, // our API client
    app: App, // our Application, see below
    /// Components registry.
    components: HashMap<UiComponentId, ComponentWrapper>, // more details later, and a ComponentWrapper FYI is mainly for elapsed "ticks" tracking
}

pub async fn run(&mut self, rx: Receiver<UserInterfaceEvent>) -> Result<()> {
        let contextual_helper = ContextualHelper::new();
        'ui: loop {
            let app = &mut self.app;
            let components = &mut self.components;

            // first, we render
            self.terminal
                .draw(|frame| {
                    // ...some layout computation here

                    // refresh application layout "chunks"
                    app.update_layout(/** ... */);

                    // render components
                    for (id, wrapper) in components.iter_mut() { // kind of like Object.entries in modern Javascript
                        // get the component placing and size, we'll see later how it's computed; it can be None...
                        let component_rendering_rect =
                            app.get_component_rendering_rect(id).cloned();
                        // ...and if None, the component will neither be drawn nor updated
                        wrapper.active = component_rendering_rect.is_some();
                        let app_context = app.get_context(); // annoying Rust borrow-checker limitation
                        match component_rendering_rect {
                            None => (), // no rendering
                            Some(inside_rect) => wrapper
                                .component
                                .render(frame, inside_rect, &app_context)
                                .expect("main UI loop: no component rendering error"), // needed invariant so this is an unrecoverable error
                        }
                    }

                    // ...render contextual helper if toggled in the settings
                })
                .map_err(HnCliError::IoError)?; // thiserror avoids me error propagation boilerplate

            // do we have a key event sent from the event polling thread?
            if let UserInterfaceEvent::KeyEvent(event) = rx.recv()? {
                // Propagate it to the Application
                app.pump_event(event);
                let app_context = app.get_context();
                let inputs = app_context.get_inputs();
                if inputs.is_active(&ApplicationAction::Quit) {
                    break 'ui; // a nice feature of Rust you may have picked on: loops can be labeled; useful in nested loops, here used to be more explicit
                }
                if inputs.is_active(&ApplicationAction::QuitShortcut)
                    && self.can_quit_via_shortcut() // quick shortcut that can be toggled in the settings, basically hitting 'q' in any screen
                {
                    break 'ui;
                }
                // first, we let the Application handle the inputs, which means the current Screeen handles it
                // it can be "swallowed" (not propagated, more details later) or passed down to the Components via the UI, see later
                if self.app.handle_inputs() && !self.handle_inputs()? {
                    // can't go into details but basically needed for the UX I wanted
                    self.app.update_latest_interacted_with_component(None);
                }
            } else {
              // else: we have a Tick update, which means let's update things that need it (current Screen, active components).
              // You'll see later that components are of course not constantly updated as fast as possible,
              // but this is not the scope of the UI structure. It just fires away.
              self.update().await?; // asynchronous since data fetching needs to happen at some point somewhere
            }
        }

        Ok(())
    }

/// Interact with application state from the components.
pub struct AppContext<'a> {
    state: &'a mut AppState,
    router: &'a mut AppRouter,
    config: &'a mut AppConfiguration,
    inputs: &'a InputsController,
    history: &'a mut AppHistory,
    /// Stored to change screen on route change.
    screen: &'a mut Box<dyn Screen>, // heap-allocated storage of a generic implementation of a Screen
}

/// Global application state.
#[derive(Debug)]
pub struct AppState {
    /// Latest component interacted with, *i.e.* the latest component having
    /// swallowed an UI event.
    latest_interacted_with_component: Option<UiComponentId>, // small precision: an Option in Rust = can contain something, or None
    /// The currently viewed item (not a comment).
    currently_viewed_item: Option<DisplayableHackerNewsItem>, // comes from our API client
    /// The comments of the currently viewed item, if applicable.
    currently_viewed_item_comments: Option<DisplayableHackerNewsItemComments>, // same thing, API client
    /// The successive IDs of the viewed comment, starting at the root parent comment.
    currently_viewed_item_comments_chain: Vec<HnItemIdScalar>, // a Vec is an heap-allocated array (a bit like C++'s std:vector)
}

/// All the possible routes in the application.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AppRoute {
    /// Home screen.
    Home(HnStoriesSections), // stores the particular Hacker News top section viewed: Home, Ask, Show, Jobs
    /// Item details screen.
    ItemDetails(DisplayableHackerNewsItem), //  stores the currently viewed item (in this case top-level = story, job, poll)
    /// Item sub-comments screen.
    ItemSubComments(DisplayableHackerNewsItem), // stores the currently viewed item (in this case a comment)
    /// Settings screen.
    Settings,
    /// Help screen.
    Help,
}

/// Stack-based global application router.
pub struct AppRouter {
    /// The current navigation stack.
    ///
    /// Example: home > story #1 details > comment #2 thread.
    navigation_stack: Vec<AppRoute>,
}

impl AppRouter {
    /// Are we on the root screen, *i.e.* the initial screen showed on application launch?
    ///
    /// NB: section tabs like "Ask HN" or similar **do** count as being on the initial screen.
    pub fn is_on_root_screen(&self) -> bool

    /// Get the current route state.
    pub fn get_current_route(&self) -> &AppRoute

    /// Push a new navigation route state.
    pub fn push_navigation_stack(&mut self, route: AppRoute)

    /// Go to the previous navigation route state.
    pub fn pop_navigation_stack(&mut self) -> Option<AppRoute>

    pub fn build_screen_from_route(route: AppRoute) -> Box<dyn Screen> // in this case, pointer to a heap-allocated generic implementation of the Screen trait (see later)
}

pub enum ApplicationAction {
    // general
    OpenExternalOrHackerNewsLink,
    OpenHackerNewsLink,
    SelectItem,
    ToggleHelp,
    Back,
    Quit,
    QuitShortcut,
    // navigation
    NavigateUp,
    NavigateDown,
    NavigateLeft,
    NavigateRight,
    // input
    ...
    // home screen
    HomeToggleSortingOption,
    HomeToggleSearchMode,
    // item screen
    ItemToggleComments,
    ItemExpandFocusedComment,
    // settings screen
    SettingsToggleControl,
}

/// Abstraction over a key event.
///
/// Used to abstract over tui's backend, and to facilitate user configuration.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Key {
    None, // needed when no event
    /// Escape key.
    Escape,
    /// Enter/Return and Numpad Enter.
    Enter,
    /// Backspace key.
    Backspace,
    /// Tabulation key.
    Tab,
    /// Up arrow.
    Up,
    /// Down arrow.
    Down,
    /// Left arrow.
    Left,
    /// Right arrow.
    Right,
    /// Keyboard character.
    Char(char),
    /// Unhandled.
    Other,
}

/// Abstraction over a key event modifier.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum KeyModifier {
    None, // needed when no key modifier
    Shift,
    Control,
}

impl ApplicationAction {
    pub fn matches_event(&self, inputs: &InputsController) -> bool {
        use ApplicationAction::*;
        match self {
            OpenExternalOrHackerNewsLink => inputs.key == Key::Char('o'),
            OpenHackerNewsLink => {
                inputs.modifier == KeyModifier::Shift && inputs.key == Key::Char('o')
            }
            // ...
        }
    }
}

/// Application inputs controller.
///
/// Bridges between raw inputs and application-level events.
#[derive(Debug)]
pub struct InputsController {
    key: Key,
    modifier: KeyModifier,
    active_input_key: Key,
    active_input_mode: bool,
}

impl InputsController {
    pub fn new() -> Self {
        Self {
            key: Key::None,
            modifier: KeyModifier::None,
            active_input_key: Key::None,
            active_input_mode: false,
        }
    }

    pub fn pump_event(&mut self, event: KeyEvent, state: &AppState) {
        // ...from a raw crossterm event, update the internal state of self
    }

    pub fn is_active(&self, action: &ApplicationAction) -> bool {
        action.matches_event(self)
    }

    pub fn has_ctrl_modifier(&self) -> bool {
        self.modifier == KeyModifier::Control
    }

    pub fn has_shift_modifier(&self) -> bool {
        self.modifier == KeyModifier::Shift
    }

    pub fn get_active_input_key(&self) -> Option<(Key, char)> {
        // get the active (keyboard key, UTF-8 character) tuple
    }
}

/// Maximum number of entries that will be kept in the history file.
pub const SYNCHRONIZED_HISTORY_ITEMS_LIMIT: usize = 500;

/// Responsible for restoring navigation state in the application from previous sessions.
#[derive(Debug)]
pub struct AppHistory {
    /// File-synchronized part of the navigation History.
    ///
    /// Reading must be done at application startup, and writing as rarely as possible.
    synchronized: SynchronizedHistory,
}

impl AppHistory {
    pub fn restored() -> Self { /* ... */ }

    /// Persist the history in OS-dependent JSON storage.
    ///
    /// Should not be called too often for performance reasons.
    pub fn persist(&self) { /* ... */ }

    pub fn persist_top_level_comment_id_for_story(
        &mut self,
        story_id: HnItemIdScalar,
        top_level_comment_id: HnItemIdScalar,
    ) { /* ... */ }

    pub fn restored_top_level_comment_id_for_story(
        &self,
        story_id: HnItemIdScalar,
    ) -> Option<HnItemIdScalar>  { /* ... */ }

    fn get_history_file_path() -> Result<PathBuf> { /* ... */ }
}

#[derive(Clone, Debug, PartialEq, PartialOrd, Serialize, Deserialize)]
pub enum SynchronizedHistoryItem {
    /// Saves the navigation state of a top-level comment for a given Item thread.
    TopLevelComment(TopLevelCommentHistoryData),
}

type SynchronizedHistoryItemStorage = HashMap<HnItemIdScalar, SynchronizedHistoryItem>;

#[derive(Debug, Deserialize, Serialize)]
pub struct SynchronizedHistory {
    /// Stores the latest focused top-level comment for a given Hacker News item.
    ///
    /// Also keeps track of the insertion datetime to enforce hard limits on the history size.
    latest_top_level_comments_per_item_map: SynchronizedHistoryItemStorage,
}

/// Defines layout state by associating each visible component
/// with a defined rendering target `Rect`.
pub type ScreenComponentsRegistry = HashMap<UiComponentId, Rect>;

/// A Screen is a self-contained state of the application with its own update and rendering logic.
pub trait Screen: Debug + Send {
    /// Called after instantiation and before mounting the screen.
    fn before_mount(&mut self, state: &mut AppState, config: &AppConfiguration) {}

    /// Handle an incoming key event, at the application level.
    ///
    /// Returns the (event_response, new_route_if_navigated) tuple.
    fn handle_inputs(
        &mut self,
        inputs: &InputsController,
        router: &mut AppRouter,
        state: &mut AppState,
        history: &mut AppHistory,
    ) -> (ScreenEventResponse, Option<AppRoute>);

    /// Compute the components' layout according to current terminal frame size.
    fn compute_layout(
        &self,
        frame_size: Rect,
        components_registry: &mut ScreenComponentsRegistry,
        state: &AppState,
    );
}

/// Actions requested by a Screen when handling an input event.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ScreenEventResponse {
    /// Swallow the event, preventing it from bubbling down to the components.
    Caught,
    /// Ignore the event, passing it down to the components.
    PassThrough,
}

/// The Home screen of hncli.
///
/// The current layout is as following:
///
/// ```md
/// ------------------------------------------
/// |              navigation                |
/// ------------------------------------------
/// |                                        |
/// |                                        |
/// |               stories                  |
/// |                                        |
/// |                                        |
/// ------------------------------------------
/// |          options (eg. sorting)         |
/// ------------------------------------------
/// ```
#[derive(Debug)]
pub struct HomeScreen {
    section: HnStoriesSections, // home, ask, show HN, jobs
}

impl HomeScreen {
    pub fn new(section: HnStoriesSections) -> Self {
        Self { section }
    }
}

impl Screen for HomeScreen {
    fn before_mount(&mut self, state: &mut AppState, config: &AppConfiguration) {
        state.set_main_stories_section(self.section);
    }

    fn handle_inputs(
        &mut self,
        inputs: &InputsController,
        router: &mut AppRouter,
        state: &mut AppState,
    ) -> (ScreenEventResponse, Option<AppRoute>) {
        if inputs.is_active(&ApplicationAction::HomeToggleSearchMode) {
            state.set_main_search_mode_query(if state.get_main_search_mode_query().is_some() {
                None
            } else {
                Some("".into())
            });
            (ScreenEventResponse::Caught, None)
        } else {
            (ScreenEventResponse::PassThrough, None)
        }
    }

    fn compute_layout(
        &self,
        frame_size: Rect,
        components_registry: &mut ScreenComponentsRegistry,
        state: &AppState,
    ) {
        // main layout chunks (think of it as a kind of column-first flexbox in CSS3)
        let main_layout_chunks = Layout::default()
            .direction(Direction::Vertical)
            .margin(2)
            .constraints(
                [
                    Constraint::Percentage(6),
                    Constraint::Percentage(89),
                    Constraint::Percentage(5),
                ]
                .as_ref(),
            )
            .split(frame_size);

        // ...now we just insert the appropriate components in each of our "chunks", by unique ID
        components_registry.insert(
            if state.get_main_search_mode_query().is_some() {
                SEARCH_ID
            } else {
                NAVIGATION_ID
            },
            main_layout_chunks[0],
        );
        components_registry.insert(STORIES_PANEL_ID, main_layout_chunks[1]);
        components_registry.insert(OPTIONS_ID, main_layout_chunks[2]);
    }
}

/// A `tick` is a UI update, in the order of the hundred milliseconds.
pub type UiTickScalar = u64;

/// A hashable type for application-unique component IDs.
pub type UiComponentId = &'static str; // hardcoded, stack-allocated string

/// A `Component` in this Terminal UI context is a self-contained
/// widget or group of widgets with each their own updating,
/// events handling and rendering logic.
#[async_trait]
pub trait UiComponent {
    /// Must return a constant, **application-unique** component ID.
    fn id(&self) -> UiComponentId;

    /// Called at instantiation, before any update or render pass.
    fn before_mount(&mut self, ctx: &mut AppContext) {}

    /// Must return `true` if the state should update itself.
    fn should_update(&mut self, elapsed_ticks: UiTickScalar, ctx: &AppContext) -> Result<bool>;

    /// Update the state from various sources.
    async fn update(&mut self, client: &mut HnClient, ctx: &mut AppContext) -> Result<()>;

    /// Inputs handler for the component.
    ///
    /// Returns true if the active event is to be captured, that is swallowed
    /// and no longer passed to other components.
    fn handle_inputs(&mut self, ctx: &mut AppContext) -> Result<bool>;

    /// Renderer for the component.
    fn render(
        &mut self,
        f: &mut Frame<CrosstermBackend<Stdout>>, // the tui-rs rendering target handle
        inside: Rect, // where to render exactly
        ctx: &AppContext,
    ) -> Result<()>;
}

/// Item details component.
///
/// Does not do any fetching, everything is pre-cached.
///
/// ```md
/// ___________________________________________
/// |                                         |
/// |                <TITLE>                  |
/// |            <URL HOSTNAME?>              |
/// |      <SCORE> POINTS / BY <USERNAME>     |
/// |   <#COMMENTS COUNT>  / POSTED <X> AGO   |
/// |_________________________________________|
/// ```
#[derive(Debug, Default)]
pub struct ItemDetails {
    text: Option<String>,
}

pub const ITEM_DETAILS_ID: UiComponentId = "item_details";

#[async_trait]
impl UiComponent for ItemDetails {
    fn id(&self) -> UiComponentId {
        ITEM_DETAILS_ID
    }

    fn should_update(&mut self, _elapsed_ticks: UiTickScalar, ctx: &AppContext) -> Result<bool> {
        // basically, returns: current_item.text (live) != self.text (cached)
    }

    async fn update(&mut self, _client: &mut HnClient, ctx: &mut AppContext) -> Result<()> {
        // just performs self.text = current_item.text
    }

    fn handle_inputs(&mut self, _ctx: &mut AppContext) -> Result<bool> {
        Ok(false) // passive component: no inputs handling
    }

    fn render(
        &mut self,
        f: &mut tui::Frame<CrosstermBackend<Stdout>>,
        inside: Rect,
        ctx: &AppContext,
    ) -> Result<()> {
        // ...rendering using first-class widgets of tui-rs, in this case a rounded Block and a multi-lines Paragraph
    }
}

/// Common (meta-)data between top and nested components.
#[derive(Debug)]
pub struct ItemCommentsCommon {
    pub ticks_since_last_update: u64,
    pub inputs_debouncer: Debouncer,
    pub loading: bool,
    pub widget_state: ItemCommentsWidgetState,
}

/// Custom `tui-rs` widget in charge of displaying a HackerNews Item comments.
#[derive(Debug)]
pub struct ItemCommentsWidget<'a> {
    /// Persistent state.
    state: &'a ItemCommentsWidgetState,
    /// Comments of the top-level parent item.
    comments: &'a DisplayableHackerNewsItemComments,
}

impl<'a> Widget for ItemCommentsWidget<'a> {
    fn render(self, area: Rect, buf: &mut Buffer) {
        // Comment rendering
        // ...sanity checks and setup
        let focused_comment_widget = CommentWidget::with_comment(focused_comment);
        focused_comment_widget.render(
            area.inner(&Margin {
                vertical: PADDING,
                horizontal: PADDING,
            }),
            buf,
        );

        // Footer
        // ...sanity checks and setup
        let footer_area = Rect::new(
            area.left(),
            area.bottom() - FOOTER_HEIGHT - PADDING,
            area.width,
            FOOTER_HEIGHT,
        );
        let footer_text = format!("...", /* ... */);
        buf.set_string( // we directly use tui-rs's low-level rendering facilities
            (footer_area.right() - footer_area.left()) / 2 - footer_text.width() as u16 / 2, // horizontal centering
            footer_area.y,
            footer_text,
            Style::default().fg(Color::LightBlue), // set the text color
        )
    }
}

/// Persistent state of `ItemCommentsWidget`.
#[derive(Debug, Default)]
pub struct ItemCommentsWidgetState {
    /// ID of the currently focused comment.
    focused_comment_id: Option<HnItemIdScalar>,
    /// Index of the currently focused comment, among the parent item's kids (starts at 0).
    focused_comment_index: Option<usize>,
    /// Number of same-level comments currently being offered for display.
    focused_same_level_comments_count: usize,
    /// If Some, prepare to restore from history navigation state the focused comment.
    history_should_focus_comment_id: Option<HnItemIdScalar>,
}

impl ItemCommentsWidgetState {
    pub fn update(
        &mut self,
        comments: &DisplayableHackerNewsItemComments,
        parent_item_kids: &[HnItemIdScalar],
    ) {
        self.reconciliate_focused_comment(comments, parent_item_kids);
    }

    pub fn previous_main_comment(
        &mut self,
        parent_item_kids: &[HnItemIdScalar],
    ) -> Option<HnItemIdScalar> { /** ... */ }

    pub fn next_main_comment(
        &mut self,
        parent_item_kids: &[HnItemIdScalar],
    ) -> Option<HnItemIdScalar> { /** ... */ }

    pub fn get_focused_comment_id(&self) -> Option<HnItemIdScalar> {
        self.focused_comment_id
    }

    pub fn restore_focused_comment_id(
        &mut self,
        comment_id: HnItemIdScalar,
        parent_item_kids: &[HnItemIdScalar],
    ) { /** ... */ }

    pub fn history_prepare_focus_on_comment_id(
        &mut self,
        history_focused_comment_id: HnItemIdScalar,
    ) {
        self.history_should_focus_comment_id = Some(history_focused_comment_id);
    }

    pub fn get_focused_same_level_comments_count(&self) -> usize {
        self.focused_same_level_comments_count
    }

    /// Reconciliate the currently focused main-level comment when replacing
    /// the comments of a currently viewed HackerNews item.
    ///
    /// Takes into account the past navigation history, if any pending.
    fn reconciliate_focused_comment(
        &mut self,
        comments: &DisplayableHackerNewsItemComments,
        parent_item_kids: &[HnItemIdScalar],
    ) { /** ... */ s}

    /// Reset the currently focused main-level comment to the first possible
    /// main-level comment, if any.
    fn reset_focused_comment(
        &mut self,
        parent_item_kids: &[HnItemIdScalar],
    ) -> Option<HnItemIdScalar> { /** ... */ }
}