headless_lms_models/
lib.rs

1/*!
2Functions and structs for interacting with the database.
3
4Each submodule corresponds to a database table.
5*/
6// we always use --document-private-items, so this warning is moot
7#![allow(rustdoc::private_intra_doc_links)]
8pub mod certificate_configuration_to_requirements;
9pub mod certificate_configurations;
10pub mod certificate_fonts;
11pub mod chapters;
12pub mod chatbot_configurations;
13pub mod chatbot_conversation_messages;
14pub mod chatbot_conversation_messages_citations;
15pub mod chatbot_conversations;
16pub mod chatbot_page_sync_statuses;
17pub mod code_giveaway_codes;
18pub mod code_giveaways;
19pub mod course_background_question_answers;
20pub mod course_background_questions;
21pub mod course_custom_privacy_policy_checkbox_texts;
22pub mod course_exams;
23pub mod course_instance_enrollments;
24pub mod course_instances;
25pub mod course_language_groups;
26pub mod course_module_completion_registered_to_study_registries;
27pub mod course_module_completions;
28pub mod course_modules;
29pub mod courses;
30pub mod email_deliveries;
31pub mod email_templates;
32pub mod ended_processed_exams;
33pub mod exams;
34pub mod exercise_language_groups;
35pub mod exercise_repositories;
36pub mod exercise_reset_logs;
37pub mod exercise_service_info;
38pub mod exercise_services;
39pub mod exercise_slide_submissions;
40pub mod exercise_slides;
41pub mod exercise_task_gradings;
42pub mod exercise_task_regrading_submissions;
43pub mod exercise_task_submissions;
44pub mod exercise_tasks;
45pub mod exercises;
46pub mod feedback;
47pub mod file_uploads;
48pub mod flagged_answers;
49pub mod generated_certificates;
50pub mod glossary;
51pub mod join_code_uses;
52pub mod library;
53pub mod marketing_consents;
54pub mod material_references;
55pub mod offered_answers_to_peer_review_temporary;
56pub mod open_university_registration_links;
57pub mod organizations;
58pub mod other_domain_to_course_redirections;
59pub mod page_audio_files;
60pub mod page_history;
61pub mod page_language_groups;
62pub mod page_visit_datum;
63pub mod page_visit_datum_daily_visit_hashing_keys;
64pub mod page_visit_datum_summary_by_courses;
65pub mod page_visit_datum_summary_by_courses_countries;
66pub mod page_visit_datum_summary_by_courses_device_types;
67pub mod page_visit_datum_summary_by_pages;
68pub mod pages;
69pub mod partner_block;
70pub mod peer_or_self_review_configs;
71pub mod peer_or_self_review_question_submissions;
72pub mod peer_or_self_review_questions;
73pub mod peer_or_self_review_submissions;
74pub mod peer_review_queue_entries;
75pub mod pending_roles;
76pub mod playground_examples;
77pub mod privacy_link;
78pub mod proposed_block_edits;
79pub mod proposed_page_edits;
80pub mod regradings;
81pub mod rejected_exercise_slide_submissions;
82pub mod repository_exercises;
83pub mod research_forms;
84pub mod roles;
85pub mod student_countries;
86pub mod study_registry_registrars;
87pub mod suspected_cheaters;
88pub mod teacher_grading_decisions;
89pub mod url_redirections;
90pub mod user_course_instance_exercise_service_variables;
91pub mod user_course_settings;
92pub mod user_details;
93pub mod user_exercise_slide_states;
94pub mod user_exercise_states;
95pub mod user_exercise_task_states;
96pub mod user_research_consents;
97pub mod users;
98
99pub mod error;
100
101pub mod prelude;
102#[cfg(test)]
103pub mod test_helper;
104
105use futures::future::BoxFuture;
106use url::Url;
107use uuid::Uuid;
108
109pub use self::error::{ModelError, ModelErrorType, ModelResult};
110use crate::prelude::*;
111
112#[macro_use]
113extern crate tracing;
114
115/**
116Helper struct to use with functions that insert data into the database.
117
118## Examples
119
120### Usage when inserting to a database
121
122By calling `.into_uuid()` function implemented by `PKeyPolicy<Uuid>`, this enum can be used with
123SQLX queries while letting the caller dictate how the primary key should be decided.
124
125```no_run
126# use headless_lms_models::{ModelResult, PKeyPolicy};
127# use uuid::Uuid;
128# use sqlx::PgConnection;
129async fn insert(
130    conn: &mut PgConnection,
131    pkey_policy: PKeyPolicy<Uuid>,
132) -> ModelResult<Uuid> {
133    let res = sqlx::query!(
134        "INSERT INTO organizations (id) VALUES ($1) RETURNING id",
135        pkey_policy.into_uuid(),
136    )
137    .fetch_one(conn)
138    .await?;
139    Ok(res.id)
140}
141
142# async fn random_function(conn: &mut PgConnection) -> ModelResult<()> {
143// Insert using generated id.
144let foo_1_id = insert(conn, PKeyPolicy::Generate).await.unwrap();
145
146// Insert using fixed id.
147let uuid = Uuid::parse_str("8fce44cf-738e-4fc9-8d8e-47c350fd3a7f").unwrap();
148let foo_2_id = insert(conn, PKeyPolicy::Fixed(uuid)).await.unwrap();
149assert_eq!(foo_2_id, uuid);
150# Ok(())
151# }
152```
153
154### Usage in a higher-order function.
155
156When `PKeyPolicy` is used with a higher-order function, an arbitrary struct can be provided
157instead. The data can be mapped further by calling the `.map()` or `.map_ref()` methods.
158
159```no_run
160# use headless_lms_models::{ModelResult, PKeyPolicy};
161# use uuid::Uuid;
162# use sqlx::PgConnection;
163# mod foos {
164#   use headless_lms_models::{ModelResult, PKeyPolicy};
165#   use uuid::Uuid;
166#   use sqlx::PgConnection;
167#   pub async fn insert(conn: &mut PgConnection, pkey_policy: PKeyPolicy<Uuid>) -> ModelResult<()> {
168#       Ok(())
169#   }
170# }
171# mod bars {
172#   use headless_lms_models::{ModelResult, PKeyPolicy};
173#   use uuid::Uuid;
174#   use sqlx::PgConnection;
175#   pub async fn insert(conn: &mut PgConnection, pkey_policy: PKeyPolicy<Uuid>) -> ModelResult<()> {
176#       Ok(())
177#   }
178# }
179
180struct FooBar {
181    foo: Uuid,
182    bar: Uuid,
183}
184
185async fn multiple_inserts(
186    conn: &mut PgConnection,
187    pkey_policy: PKeyPolicy<FooBar>,
188) -> ModelResult<()> {
189    foos::insert(conn, pkey_policy.map_ref(|x| x.foo)).await?;
190    bars::insert(conn, pkey_policy.map_ref(|x| x.bar)).await?;
191    Ok(())
192}
193
194# async fn some_function(conn: &mut PgConnection) {
195// Insert using generated ids.
196assert!(multiple_inserts(conn, PKeyPolicy::Generate).await.is_ok());
197
198// Insert using fixed ids.
199let foobar = FooBar {
200    foo: Uuid::parse_str("52760668-cc9d-4144-9226-d2aacb83bea9").unwrap(),
201    bar: Uuid::parse_str("ce9bd0cd-0e66-4522-a1b4-52a9347a115c").unwrap(),
202};
203assert!(multiple_inserts(conn, PKeyPolicy::Fixed(foobar)).await.is_ok());
204# }
205```
206*/
207pub enum PKeyPolicy<T> {
208    /// Ids will be generated based on the associated data. Usually only used in
209    /// local test environments where reproducible database states are desired.
210    Fixed(T),
211    /// Ids will be generated on the database level. This should be the default
212    /// behavior.
213    Generate,
214}
215
216impl<T> PKeyPolicy<T> {
217    /// Gets reference to the fixed data, if there are any.
218    pub fn fixed(&self) -> Option<&T> {
219        match self {
220            PKeyPolicy::Fixed(t) => Some(t),
221            PKeyPolicy::Generate => None,
222        }
223    }
224
225    /// Maps `PKeyPolicy<T>` to `PKeyPolicy<U>` by applying a function to the contained value.
226    pub fn map<U, F>(self, f: F) -> PKeyPolicy<U>
227    where
228        F: FnOnce(T) -> U,
229    {
230        match self {
231            PKeyPolicy::Fixed(x) => PKeyPolicy::Fixed(f(x)),
232            PKeyPolicy::Generate => PKeyPolicy::Generate,
233        }
234    }
235
236    /// Maps a reference of contained data in `Fixed(T)` to `PKeyPolicy<U>` by applying a function
237    /// to the contained value. This is useful whenever a referenced value can be used instead of
238    /// having to consume the original value.
239    pub fn map_ref<U, F>(&self, f: F) -> PKeyPolicy<U>
240    where
241        F: FnOnce(&T) -> U,
242    {
243        match self {
244            PKeyPolicy::Fixed(x) => PKeyPolicy::Fixed(f(x)),
245            PKeyPolicy::Generate => PKeyPolicy::Generate,
246        }
247    }
248}
249
250impl PKeyPolicy<Uuid> {
251    /// Maps into the contained `Uuid` value or generates a new one.
252    pub fn into_uuid(self) -> Uuid {
253        match self {
254            PKeyPolicy::Fixed(uuid) => uuid,
255            PKeyPolicy::Generate => Uuid::new_v4(),
256        }
257    }
258}
259
260/// Many database tables are related to either a course or an exam
261#[derive(Clone, Copy)]
262pub enum CourseOrExamId {
263    Course(Uuid),
264    Exam(Uuid),
265}
266
267impl CourseOrExamId {
268    pub fn from(course_id: Option<Uuid>, exam_id: Option<Uuid>) -> ModelResult<Self> {
269        match (course_id, exam_id) {
270            (Some(course_id), None) => Ok(Self::Course(course_id)),
271            (None, Some(exam_id)) => Ok(Self::Exam(exam_id)),
272            (Some(_), Some(_)) => Err(ModelError::new(
273                ModelErrorType::Generic,
274                "Database row had both a course id and an exam id".to_string(),
275                None,
276            )),
277            (None, None) => Err(ModelError::new(
278                ModelErrorType::Generic,
279                "Database row did not have a course id or an exam id".to_string(),
280                None,
281            )),
282        }
283    }
284
285    pub fn to_course_and_exam_ids(self) -> (Option<Uuid>, Option<Uuid>) {
286        match self {
287            Self::Course(instance_id) => (Some(instance_id), None),
288            Self::Exam(exam_id) => (None, Some(exam_id)),
289        }
290    }
291    pub fn exam_id(self) -> Option<Uuid> {
292        if let CourseOrExamId::Exam(id) = self {
293            Some(id)
294        } else {
295            None
296        }
297    }
298}
299
300/// A "trait alias" so this `for<'a>` ... string doesn't need to be repeated everywhere
301/// Arguments:
302///   `Url`: The URL that the request is sent to (the exercise service's endpoint)
303///   `&str`: Exercise type/service slug
304///   `Option<Value>`: The Json for the request, for example the private spec in a public spec request
305pub trait SpecFetcher:
306    for<'a> Fn(
307    Url,
308    &'a str,
309    Option<&'a serde_json::Value>,
310) -> BoxFuture<'a, ModelResult<serde_json::Value>>
311{
312}
313
314impl<
315    T: for<'a> Fn(
316        Url,
317        &'a str,
318        Option<&'a serde_json::Value>,
319    ) -> BoxFuture<'a, ModelResult<serde_json::Value>>,
320> SpecFetcher for T
321{
322}
headless_lms_models/lib.rs

headless_lms_models/
lib.rs
