docs: function/struct comments

This commit is contained in:
Greg Heartsfield 2022-02-12 09:29:35 -06:00
parent fa66a0265e
commit 26a0ce2b32
5 changed files with 21 additions and 10 deletions

View File

@ -1,4 +1,6 @@
//! Subscription close request parsing //! Subscription close request parsing
//!
//! Representation and parsing of `CLOSE` messages sent from clients.
use crate::error::{Error, Result}; use crate::error::{Error, Result};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@ -11,7 +13,7 @@ pub struct CloseCmd {
id: String, id: String,
} }
/// Close command parsed /// Identifier of the subscription to be closed.
#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)] #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct Close { pub struct Close {
/// The subscription identifier being closed. /// The subscription identifier being closed.

View File

@ -126,6 +126,7 @@ FOREIGN KEY(metadata_event) REFERENCES event(id) ON UPDATE CASCADE ON DELETE CAS
// TODO: drop the pubkey_ref and event_ref tables // TODO: drop the pubkey_ref and event_ref tables
/// Build a database connection pool.
pub fn build_pool( pub fn build_pool(
name: &str, name: &str,
flags: OpenFlags, flags: OpenFlags,
@ -469,13 +470,14 @@ pub async fn db_writer(
}) })
} }
/// Determine the current application database schema version.
pub fn db_version(conn: &mut Connection) -> Result<usize> { pub fn db_version(conn: &mut Connection) -> Result<usize> {
let query = "PRAGMA user_version;"; let query = "PRAGMA user_version;";
let curr_version = conn.query_row(query, [], |row| row.get(0))?; let curr_version = conn.query_row(query, [], |row| row.get(0))?;
Ok(curr_version) Ok(curr_version)
} }
/// Persist an event to the database. /// Persist an event to the database, returning rows added.
pub fn write_event(conn: &mut PooledConnection, e: &Event) -> Result<usize> { pub fn write_event(conn: &mut PooledConnection, e: &Event) -> Result<usize> {
// start transaction // start transaction
let tx = conn.transaction()?; let tx = conn.transaction()?;
@ -549,7 +551,7 @@ pub fn write_event(conn: &mut PooledConnection, e: &Event) -> Result<usize> {
Ok(ins_count) Ok(ins_count)
} }
/// Event resulting from a specific subscription request /// Serialized event associated with a specific subscription request.
#[derive(PartialEq, Debug, Clone)] #[derive(PartialEq, Debug, Clone)]
pub struct QueryResult { pub struct QueryResult {
/// Subscription identifier /// Subscription identifier
@ -568,6 +570,7 @@ fn is_all_fs(s: &str) -> bool {
s.chars().all(|x| x == 'f' || x == 'F') s.chars().all(|x| x == 'f' || x == 'F')
} }
/// Types of hexadecimal queries.
#[derive(PartialEq, Debug, Clone)] #[derive(PartialEq, Debug, Clone)]
enum HexSearch { enum HexSearch {
// when no range is needed, exact 32-byte // when no range is needed, exact 32-byte
@ -637,6 +640,7 @@ fn hex_range(s: &str) -> Option<HexSearch> {
Some(HexSearch::Range(base, upper)) Some(HexSearch::Range(base, upper))
} }
/// Produce a arbitrary list of '?' parameters.
fn repeat_vars(count: usize) -> String { fn repeat_vars(count: usize) -> String {
if count == 0 { if count == 0 {
return "".to_owned(); return "".to_owned();

View File

@ -16,17 +16,18 @@ use std::str::FromStr;
use std::time::SystemTime; use std::time::SystemTime;
lazy_static! { lazy_static! {
/// Secp256k1 verification instance.
pub static ref SECP: Secp256k1<VerifyOnly> = Secp256k1::verification_only(); pub static ref SECP: Secp256k1<VerifyOnly> = Secp256k1::verification_only();
} }
/// Event command in network format /// Event command in network format.
#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)] #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct EventCmd { pub struct EventCmd {
cmd: String, // expecting static "EVENT" cmd: String, // expecting static "EVENT"
event: Event, event: Event,
} }
/// Event parsed /// Parsed nostr event.
#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)] #[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct Event { pub struct Event {
pub id: String, pub id: String,
@ -71,7 +72,7 @@ impl From<EventCmd> for Result<Event> {
} }
} }
/// Seconds since 1970 /// Seconds since 1970.
pub fn unix_time() -> u64 { pub fn unix_time() -> u64 {
SystemTime::now() SystemTime::now()
.duration_since(SystemTime::UNIX_EPOCH) .duration_since(SystemTime::UNIX_EPOCH)

View File

@ -8,4 +8,3 @@ pub mod info;
pub mod nip05; pub mod nip05;
pub mod protostream; pub mod protostream;
pub mod subscription; pub mod subscription;
pub mod tags;

View File

@ -1,4 +1,9 @@
//! User verification using NIP-05 names //! User verification using NIP-05 names
//!
//! NIP-05 defines a mechanism for authors to associate an internet
//! address with their public key, in metadata events. This module
//! consumes a stream of metadata events, and keeps a database table
//! updated with the current NIP-05 verification status.
use crate::config::SETTINGS; use crate::config::SETTINGS;
use crate::db; use crate::db;
use crate::error::{Error, Result}; use crate::error::{Error, Result};
@ -15,7 +20,7 @@ use std::time::Instant;
use std::time::SystemTime; use std::time::SystemTime;
use tokio::time::Interval; use tokio::time::Interval;
/// NIP-05 verifier /// NIP-05 verifier state
pub struct Verifier { pub struct Verifier {
/// Metadata events for us to inspect /// Metadata events for us to inspect
metadata_rx: tokio::sync::broadcast::Receiver<Event>, metadata_rx: tokio::sync::broadcast::Receiver<Event>,
@ -649,8 +654,7 @@ pub async fn save_verification_record(
}).await? }).await?
} }
/// Retrieve the most recent verification record for a given pubkey /// Retrieve the most recent verification record for a given pubkey (async).
// Important, this is the most recent verification /of the most recent metadata event/.
pub async fn get_latest_user_verification( pub async fn get_latest_user_verification(
conn: db::PooledConnection, conn: db::PooledConnection,
pubkey: &str, pubkey: &str,
@ -659,6 +663,7 @@ pub async fn get_latest_user_verification(
tokio::task::spawn_blocking(move || query_latest_user_verification(conn, p)).await? tokio::task::spawn_blocking(move || query_latest_user_verification(conn, p)).await?
} }
/// Query database for the latest verification record for a given pubkey.
pub fn query_latest_user_verification( pub fn query_latest_user_verification(
mut conn: db::PooledConnection, mut conn: db::PooledConnection,
pubkey: String, pubkey: String,