API simples de registro de ponto em rust + axum em single-file. Objetivo: fazer API lidar com autenticação por JWT, hashing de senha, manipular banco Postgree ou dados em Memória. Deliberadamente feita em single-file. Ainda em construção.

README.md

FLPoint-Rust

O presente repositório mantém o código fonte de backend simples para gerenciamento de registros de Ponto Eletrônico.

Ponto eletrônico refere-se ao instante no qual um funcionário chega e/ou sai de seu trabalho. Um sistema de ponto eletrônico serve para gerenciar registros desses instantes, ou seja, o sistema serve para guardar os registros em algum banco de dados para posteriores usos.

Os usos posteriores podem ser variados, como por exemplo elaboração de relatório de horas extra.

Este projeto visa prover uma aplicação de categoria backend para permitir que tais operações sejam realizadas, em arquitetura de cliente/servidor.

Implementação

O sistema é implementado em arquitetura de cliente/servidor, onde o presente código é referente à parte do servidor. Futuramente poderá ser incluído código para a parte de um cliente.

O servidor é construído em cima do estilo de servidor que expõe suas funções através de uma API RESTful, ou seja, as funcionalidades são expostas via URLs de endpoints específicos, os quais respondem ao protocolo HTTP.

Para que os registros de ponto sejam gerenciados, o projeto define que, primariamente, os usuários necessitam de estar devidamente registrados no sistema. Tendo isso sido satisfeito, os usuários devem se autenticar no sistema, usando a estratégia de login, para, então, realizar a criação de um registro de ponto no sistema.

O requerimento da necessidade de registro obrigatório de usuários foi escolhido visto que, dessa forma, se torna mais simples e direta a associação e/ou relação entre os dados referentes a registros de ponto e um usuário específico.

Tech stack

Esse projeto, inicialmente, foi implementado usando ferramentas do ecossistema Kotlin, porém, no presente repositório, temos a implementação desse projeto usando ferramentas do ecossistema Rust. No geral, as ferramentas e bibliotecas escolhidas para a composição do sistema são:

• Rust como linguagem de programação principal;
• Axum como webserver;
• jsonwebtoken para geração e verificação de JWT;
• chrono para gerenciamento de data/tempo;
• PostgreSQL como gerenciador de dados de produção;
• Docker para transformação do projeto em um contêiner reprodutível.

Além disso, o projeto está sendo desenvolvido usando um arquivo único, o que é apenas uma decisão arbitrária do desenvolvedor. Portanto, todo o código referente a todos os itens necessários para que o sistema funcione está presente no arquivo main.rs.

Lembramos também que, apesar do código de toda a aplicação estar inteiramente em um único arquivo, o mesmo foi marcado comentários "<editor-fold>", o que permite a expansão ou colapso automáticos dos blocos de código marcados por tal estrura. Porém, essa estrutura foi testada apenas nos editores/IDEs baseados em IntelliJ, o que pode não funcionar em outros editores populares, como o VSCode.

Executando

As instruções de execução serão atualizadas assim que o projeto sair de fase de desenvolvimento.

Cargo.toml

[package]
name = "FLPoint-Rust"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
axum = "0.7.5"
axum-extra = { version = "0.9.3", features = ["typed-header"] }
chrono = { version = "0.4.38", features = ["now", "clock", "alloc", "std", "serde"] }
jsonwebtoken = "9.3.0"
serde = { version = "1.0.210", features = ["derive"] }
serde_json = "1.0.128"
tokio = { version = "1.40.0", features = ["full"] }

main.rs

use axum::extract::State;
use axum::handler::Handler;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::routing::post;
use axum::{routing::get, Json, Router};
use axum_extra::either::Either;
use axum_extra::headers::authorization::Bearer;
use axum_extra::headers::Authorization;
use axum_extra::TypedHeader;
use bcrypt::{hash, verify, DEFAULT_COST};
use chrono::{DateTime, Local, TimeDelta};
use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};
use std::error::Error;
use std::sync::{Arc, Mutex};

//<editor-fold desc="MODELING-SECTION">
// TODO: create a custom type to be used as response in order to no to use this type directly. E.g.: "UserResponseDTO".
#[derive(Debug, Clone, Serialize)]
pub struct User {
  pub id: usize,
  pub name: String,
  pub email: String,
  pub hashed_password: String,
  pub is_admin: bool,
}

#[derive(Debug, Clone, Serialize)]
pub struct Point {
  pub id: usize,
  pub related_user_id: usize,
  pub instant: DateTime<Local>,
}

// TODO: validate request
#[derive(Debug, Deserialize)]
pub struct CreateUserRequestDTO {
  pub name: String,
  pub email: String,
  pub plain_password: String,
}

// TODO: validate request
#[derive(Debug, Deserialize)]
pub struct CreatePointRequestDTO {
  pub related_user_id: usize,
  pub instant: DateTime<Local>,
}

// TODO: validate request
#[derive(Debug, Deserialize)]
pub struct CredentialsDTO {
  pub email: String,
  pub plain_password: String,
}
//</editor-fold

//<editor-fold desc="PASSWORD-HASHING-SECTION">
pub fn hashed_password(plain: String) -> Result<String, Box<dyn Error>> {
  Ok(hash(plain, DEFAULT_COST)?)
}

pub fn plain_matches_hashed(plain: String, hashed: String) -> Result<bool, Box<dyn Error>> {
  Ok(verify(plain, &*hashed)?)
}
//</editor-fold>

//<editor-fold desc="JWT-SECTION">
// TODO: refactor to retrieve from ENV
const JWT_SECRET: &'static str = "SECRET!";

#[derive(Debug, Serialize, Deserialize)]
pub struct JwtClaims {
  pub user_id: String,
  pub is_admin: bool,
  pub exp: usize, // in seconds
}

pub fn generate_jwt(claims: JwtClaims) -> String {
  encode(
    &Header::default(),
    &claims,
    &EncodingKey::from_secret(JWT_SECRET.as_ref()),
  ).unwrap() // handle panic?
}

pub fn token_verification_result(jwt: String) -> Result<JwtClaims, Box<dyn std::error::Error>> {
  let token_data = decode(
    jwt.as_str(),
    &DecodingKey::from_secret(JWT_SECRET.as_ref()),
    &Validation::new(Algorithm::HS256),
  )?;

  Ok(token_data.claims)
}
//</editor-fold>

//<editor-fold desc="RULES-SECTION">
pub fn is_within_time_range(check: DateTime<Local>) -> bool {
  let now = Local::now();
  let lower_bound = now - TimeDelta::seconds(10);
  let higher_bound = now + TimeDelta::seconds(1);
  check >= lower_bound && check <= higher_bound
}

pub fn passed_at_least_30_min_from_last(last: DateTime<Local>, check: DateTime<Local>) -> bool {
  check - last >= TimeDelta::minutes(30)
}
//</editor-fold>

//<editor-fold desc="IN-MEMORY-DATA-HANDLING-SECTION">
pub struct InMemoryDataHandler {
  pub users: Mutex<Vec<User>>,
  pub points: Mutex<Vec<Point>>,
}

impl InMemoryDataHandler {
  pub fn new() -> Self {
    InMemoryDataHandler {
      users: Mutex::new(Vec::new()),
      points: Mutex::new(Vec::new()),
    }
  }

  pub fn create_user(&self, dto: CreateUserRequestDTO, create_as_admin: bool) -> impl IntoResponse {
    let mut users = self.users.lock().unwrap();
    match users.iter().find(|u| u.email == dto.email) {
      Some(_) => { (StatusCode::BAD_REQUEST, "Email already exists".to_string()) }
      None => {
        match hashed_password(dto.plain_password) {
          Ok(next_hashed_password) => {
            let next_id = users.len() + 1;
            users.push(
              User {
                id: next_id,
                name: dto.name,
                email: dto.email,
                hashed_password: next_hashed_password,
                is_admin: create_as_admin,
              }
            );
            (StatusCode::CREATED, next_id.to_string())
          }
          Err(_) => {
            (StatusCode::INTERNAL_SERVER_ERROR, "Was not possible to hash the received password".to_string())
          }
        }
      }
    }
  }

  pub fn login_user(&self, dto: CredentialsDTO) -> impl IntoResponse {
    let mut users = self.users.lock().unwrap();
    let found_user = users.iter().find(|u| u.email == dto.email);
    match found_user {
      Some(user) => {
        match plain_matches_hashed(dto.plain_password, user.hashed_password.clone()) {
          Ok(password_check) => {
            if !password_check {
              return (StatusCode::BAD_REQUEST, "Passwords don't match!".to_string());
            }

            let jwt = generate_jwt(JwtClaims {
              user_id: user.id.to_string(),
              is_admin: user.is_admin,
              exp: (Local::now() + TimeDelta::minutes(10)).timestamp() as usize, // 10 minutes in future
            });

            (StatusCode::OK, jwt)
          }

          Err(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Unable to analyse password".to_string())
        }
      }
      None => (StatusCode::BAD_REQUEST, "Email not found".to_string()),
    }
  }

  pub fn get_all_app_users(&self, jwt: String) -> impl IntoResponse {
    match self.jwt_contains_an_existing_id(jwt) {
      Ok(claims) => {
        if claims.is_admin == false {
          return Either::E1((StatusCode::FORBIDDEN, "Only admins allowed".to_string()));
        }

        let users = self.users.lock().unwrap();
        let Json(json_users) = Json(users.clone());
        Either::E2((StatusCode::OK, Json(json_users)))
      }
      Err(_) => {
        Either::E1((StatusCode::BAD_REQUEST, "Invalid JWT".to_string()))
      }
    }
  }

  pub fn create_point(&self, dto: CreatePointRequestDTO, jwt: String) -> impl IntoResponse {
    let verification = token_verification_result(jwt);

    match verification {
      Ok(claims) => {
        if claims.user_id != dto.related_user_id.to_string() {
          return (StatusCode::FORBIDDEN, "Not authorized to access this!".to_string());
        }

        let mut local_points = &mut self.points.lock().unwrap();
        let related_user_points = local_points.iter().filter(|p| p.related_user_id == dto.related_user_id);
        if related_user_points.clone().count() != 0 {
          if !passed_at_least_30_min_from_last(related_user_points.last().unwrap().instant, dto.instant) {
            return (StatusCode::BAD_REQUEST, "Instant range not satisfied".to_string());
          }
        }

        let next_id = local_points.len() + 1;
        local_points.push(Point {
          id: next_id,
          related_user_id: dto.related_user_id,
          instant: dto.instant,
        });

        (StatusCode::CREATED, next_id.to_string())
      }

      Err(_) => {
        (StatusCode::BAD_REQUEST, "Invalid JWT".to_string())
      }
    }
  }

  pub fn get_all_points_of_an_user(&self, jwt: String) -> impl IntoResponse {
    match self.jwt_contains_an_existing_id(jwt.clone()) {
      Ok(claims) => {
        let filtered_points = self.points
          .lock()
          .unwrap()
          .iter()
          .filter(|p| { p.related_user_id.to_string() == claims.user_id })
          .cloned()
          .collect::<Vec<Point>>();

        let Json(json_points) = Json(filtered_points);
        Either::E1((StatusCode::OK, Json(json_points)))
      }
      Err(_) => {
        Either::E2((StatusCode::BAD_REQUEST, "Invalid JWT"))
      }
    }
  }

  pub fn get_all_app_points(&self, jwt: String) -> impl IntoResponse {
    match self.jwt_contains_an_existing_id(jwt.clone()) {
      Ok(claims) => {
        if claims.is_admin == false {
          return Either::E1((StatusCode::FORBIDDEN, "Only admins allowed"));
        }

        let retrieved_points = self.points.lock().unwrap().iter().cloned().collect::<Vec<Point>>();
        let Json(json_points) = Json(retrieved_points);

        Either::E2((StatusCode::OK, Json(json_points)))
      }
      Err(_) => {
        Either::E1((StatusCode::BAD_REQUEST, "Invalid JWT"))
      }
    }
  }

  fn jwt_contains_an_existing_id(&self, jwt: String) -> Result<JwtClaims, bool> {
    match token_verification_result(jwt) {
      Ok(claims) => {
        let users = self.users.lock().unwrap();

        if !users.iter().any(|u| u.id.to_string() == claims.user_id) {
          return Err(false);
        }

        Ok(claims)
      }
      Err(_) => Err(false)
    }
  }
}
//</editor-fold>

//<editor-fold desc="ROUTES-FUNCTIONS-SECTION">
async fn handle_signup(
  State(handler): State<Arc<InMemoryDataHandler>>,
  Json(dto): Json<CreateUserRequestDTO>,
) -> impl IntoResponse {
  handler.create_user(dto, false)
}

async fn handle_login(
  State(handler): State<Arc<InMemoryDataHandler>>,
  Json(dto): Json<CredentialsDTO>,
) -> impl IntoResponse {
  handler.login_user(dto)
}

async fn handle_create_point(
  State(handler): State<Arc<InMemoryDataHandler>>,
  TypedHeader(Authorization(bearer)): TypedHeader<Authorization<Bearer>>,
  Json(dto): Json<CreatePointRequestDTO>,
) -> impl IntoResponse {
  handler.create_point(dto, bearer.token().to_string())
}

async fn handle_get_all_user_points(
  State(handler): State<Arc<InMemoryDataHandler>>,
  TypedHeader(Authorization(bearer)): TypedHeader<Authorization<Bearer>>,
) -> impl IntoResponse {
  handler.get_all_points_of_an_user(bearer.token().to_string())
}

async fn handle_get_all_users(
  State(handler): State<Arc<InMemoryDataHandler>>,
  TypedHeader(Authorization(bearer)): TypedHeader<Authorization<Bearer>>,
) -> impl IntoResponse {
  handler.get_all_app_users(bearer.token().to_string())
}

async fn handle_get_all_points(
  State(handler): State<Arc<InMemoryDataHandler>>,
  TypedHeader(Authorization(bearer)): TypedHeader<Authorization<Bearer>>,
) -> impl IntoResponse {
  handler.get_all_app_points(bearer.token().to_string())
}
//</editor-fold>

//<editor-fold desc="MAIN-FUNCTION-SECTION">
#[tokio::main]
async fn main() {
  // we create the root state that is shared to the routes handlers
  let shared_state = Arc::new(InMemoryDataHandler::new());

  // by default creates the admin user
  // TODO: the admin credentials must comes from ENV
  shared_state.create_user(
    CreateUserRequestDTO {
      name: "System Admin".to_string(),
      email: "[email protected]".to_string(),
      plain_password: "admin".to_string(),
    },
    true,
  );

  // composes routes and shared state in the app field
  let app = Router::new()
    .route("/health", get(|| async { "Hello from Rust/Axum!" }))

    // public access routes
    .route("/signup", post(handle_signup))
    .route("/login", post(handle_login))

    // points management routes (under auth)
    .route(
      "/points",
      post(handle_create_point).get(handle_get_all_user_points),
    )

    // admin only routes
    .route("/admin/users", get(handle_get_all_users))
    .route("/admin/points", get(handle_get_all_points))

    // global routes state composition definition
    .with_state(shared_state);

  let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
  axum::serve(listener, app).await.unwrap();
}
//</editor-fold>