Refine journal interface limits, naming, and error logging (#18)

Author: thiennamdinh

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "journal-sdk"
-version = "1.1.1"
+version = "1.1.2"
 edition = "2024"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

README.md

@@ -54,15 +54,15 @@ Here are other auxiliary actions that may be useful in the course of development
 
 # Use
 
-The `interface` endpoint exposes an evaluator for executing arbitrary code in a Lisp dialect.
+The `interface` endpoint exposes an evaluator for executing arbitrary code in a Scheme dialect.
 Once the service deploys, all interaction with the Journal SDK should take place through this interface.
 The evaluator itself is stateless; all variables and computations are cleared between each invocation of the endpoint.
 However, the SDK provides a controlled ability to read and write persistent data to the backend database.
 By leveraging the functionality and workflow specified below, it is possible to create arbitrarily complex stateful interfaces that benefit from the same core cryptographic verifiability afforded by the Journal.
 
-## Lisp Evaluation
+## Scheme Evaluation
 
-The Lisp dialect used for Synchronic Web code is a lightly modified version of s7 Scheme.
+The Scheme dialect used for Synchronic Web code is a lightly modified version of s7 Scheme.
 All source code and documentation is available in the [./external/s7](./external/s7) folder.
 Other basic modifcations include:
 
@@ -91,7 +91,7 @@ There is only one structural constraint on the form of the record: for a record
 `(lambda (*sync-state* query) (cons ... *sync-state*))`
 
 The `*sync-state*` parameter is the root node of the record while the `query` parameter is the expression provided through the `/interface` endpoint.
-The function returns a Lisp pair where the first item is the response to the `/inferface` call and the second item is the new root node.
+The function returns a Scheme pair where the first item is the response to the `/inferface` call and the second item is the new root node.
 For example, the default function is the following:
 
 `(lambda (*sync-state* query) (cons (eval query) *sync-state*))`

src/lib.rs

@@ -9,7 +9,7 @@ use crate::extensions::system::{primitive_s7_system_time_unix, primitive_s7_syst
 use crate::persistor::{MemoryPersistor, PERSISTOR, Persistor, PersistorAccessError};
 pub use crate::persistor::{SIZE, Word};
 use libc;
-use log::{debug, info};
+use log::{debug, info, warn};
 use once_cell::sync::Lazy;
 use serde_json::Value;
 use std::collections::HashMap;
@@ -78,6 +78,25 @@ fn escape_scheme_string(value: &str) -> String {
     value.replace('\\', "\\\\").replace('\"', "\\\"")
 }
 
+fn truncate_for_log(value: &str, limit: usize) -> String {
+    let truncated: String = value.chars().take(limit).collect();
+    if value.chars().count() > limit {
+        format!("{truncated} ...")
+    } else {
+        truncated
+    }
+}
+
+fn warn_on_error_result(query: &str, output: &str) {
+    if output.starts_with("(error ") {
+        warn!(
+            "Evaluation returned error form. Query: {} Result: {}",
+            truncate_for_log(query, 256),
+            truncate_for_log(output, 256),
+        );
+    }
+}
+
 /// Journals are the primary way that application developers
 /// interact with the synchronic web.
 ///
@@ -88,7 +107,7 @@ fn escape_scheme_string(value: &str) -> String {
 ///
 /// * __Persistence__: managing bytes on the global hash graph
 ///
-/// * __Evaluation__: executing code in the global Lisp environment
+/// * __Evaluation__: executing code in the global Scheme environment
 ///
 /// __Records__ are the primary way that developers interface with
 /// Journals. A Record is a mapping between a constant identifier and
@@ -125,7 +144,7 @@ impl Journal {
         }
     }
 
-    /// Evaluate a Lisp expression within a Record
+    /// Evaluate a Scheme expression within a Record
     ///
     /// # Examples
     /// ```
@@ -173,17 +192,17 @@ impl Journal {
         }
     }
 
-    /// Convert a Lisp expression into its JSON representation without evaluation.
+    /// Convert a Scheme expression into its JSON representation without evaluation.
     ///
     /// # Examples
     /// ```
     /// use journal_sdk::JOURNAL;
     /// use serde_json::json;
     ///
-    /// let output = JOURNAL.lisp_to_json("(+ 1 2)");
+    /// let output = JOURNAL.scheme_to_json("(+ 1 2)");
     /// assert_eq!(output, json!(["+", 1, 2]));
     /// ```
-    pub fn lisp_to_json(&self, query: &str) -> Value {
+    pub fn scheme_to_json(&self, query: &str) -> Value {
         match lisp2json(query) {
             Ok(json_result) => json_result,
             Err(_) => {
@@ -197,17 +216,17 @@ impl Journal {
         }
     }
 
-    /// Convert a JSON expression into its Lisp representation without evaluation.
+    /// Convert a JSON expression into its Scheme representation without evaluation.
     ///
     /// # Examples
     /// ```
     /// use journal_sdk::JOURNAL;
     /// use serde_json::json;
     ///
-    /// let output = JOURNAL.json_to_lisp(json!(["+", 1, 2]));
+    /// let output = JOURNAL.json_to_scheme(json!(["+", 1, 2]));
     /// assert_eq!(output, "(+ 1 2)");
     /// ```
-    pub fn json_to_lisp(&self, query: Value) -> String {
+    pub fn json_to_scheme(&self, query: Value) -> String {
         match json2lisp(&query) {
             Ok(scheme_result) => scheme_result,
             Err(_) => {
@@ -370,6 +389,7 @@ impl Journal {
 
             match state_old == state_new {
                 true => {
+                    warn_on_error_result(query, output.as_str());
                     debug!(
                         "Completed ({:?}) {} -> {}",
                         start.elapsed(),
@@ -433,6 +453,7 @@ impl Journal {
                             match iterate(&persistor, state_new) {
                                 Ok(_) => match PERSISTOR.root_set(record, state_old, state_new) {
                                     Ok(_) => {
+                                        warn_on_error_result(query, output.as_str());
                                         debug!(
                                             "Completed ({:?}) {} -> {}",
                                             start.elapsed(),

src/main.rs

@@ -18,10 +18,10 @@ const INDEX_HTML: &str = r#"<!DOCTYPE html>
     </head>
     <body style="padding: 0 20px; font-family: 'Consolas'">
  <ul>
-     <li><a href="/interface">LISP Interface</a></li>
+     <li><a href="/interface">Scheme Interface</a></li>
      <li><a href="/interface/json">JSON Interface</a></li>
-     <li><a href="/interface/lisp-to-json">LISP to JSON</a></li>
-     <li><a href="/interface/json-to-lisp">JSON to LISP</a></li>
+     <li><a href="/interface/scheme-to-json">Scheme to JSON</a></li>
+     <li><a href="/interface/json-to-scheme">JSON to Scheme</a></li>
  </ul>
     </body>
 </html>
@@ -78,7 +78,7 @@ async fn index() -> RawHtml<String> {
 async fn inform_lisp() -> RawHtml<String> {
     RawHtml(
         INTERFACE_HTML
-            .replace("__TITLE__", "LISP Interface")
+            .replace("__TITLE__", "Scheme Interface")
             .replace("__HEADERS__", ""),
     )
 }
@@ -88,18 +88,18 @@ async fn evaluate_lisp(query: &str) -> String {
     JOURNAL.evaluate(query)
 }
 
-#[get("/interface/lisp-to-json", format = "text/html")]
-async fn inform_lisp_to_json() -> RawHtml<String> {
+#[get("/interface/scheme-to-json", format = "text/html")]
+async fn inform_scheme_to_json() -> RawHtml<String> {
     RawHtml(
         INTERFACE_HTML
-            .replace("__TITLE__", "LISP to JSON")
+            .replace("__TITLE__", "Scheme to JSON")
             .replace("__HEADERS__", ""),
     )
 }
 
-#[post("/interface/lisp-to-json", data = "<query>", rank = 1)]
-async fn lisp_to_json(query: &str) -> Json<Value> {
-    let result = JOURNAL.lisp_to_json(query);
+#[post("/interface/scheme-to-json", data = "<query>", rank = 1)]
+async fn scheme_to_json(query: &str) -> Json<Value> {
+    let result = JOURNAL.scheme_to_json(query);
     Json(result)
 }
 
@@ -121,17 +121,17 @@ async fn evaluate_json(query: Json<Value>) -> Json<Value> {
     Json(result)
 }
 
-#[get("/interface/json-to-lisp", format = "text/html")]
-async fn inform_json_to_lisp() -> RawHtml<String> {
-    RawHtml(INTERFACE_HTML.replace("__TITLE__", "JSON to LISP").replace(
+#[get("/interface/json-to-scheme", format = "text/html")]
+async fn inform_json_to_scheme() -> RawHtml<String> {
+    RawHtml(INTERFACE_HTML.replace("__TITLE__", "JSON to Scheme").replace(
         "__HEADERS__",
         "headers: { 'Content-Type': 'application/json' },",
     ))
 }
 
-#[post("/interface/json-to-lisp", data = "<query>", format = "json", rank = 1)]
-async fn json_to_lisp(query: Json<Value>) -> RawText<String> {
-    RawText(JOURNAL.json_to_lisp(query.into_inner()))
+#[post("/interface/json-to-scheme", data = "<query>", format = "json", rank = 1)]
+async fn json_to_scheme(query: Json<Value>) -> RawText<String> {
+    RawText(JOURNAL.json_to_scheme(query.into_inner()))
 }
 
 #[rocket::main]
@@ -154,7 +154,9 @@ async fn main() {
     let mut rocket_config = RocketConfig::default();
     rocket_config.port = config.port;
     rocket_config.address = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0));
-    rocket_config.limits = Limits::new().limit("string", 1_i32.mebibytes());
+    rocket_config.limits = Limits::new()
+        .limit("string", 64_i32.mebibytes())
+        .limit("json", 64_i32.mebibytes());
 
     if config.step != "" {
         tokio::spawn(async move {
@@ -195,12 +197,12 @@ async fn main() {
                 index,
                 inform_lisp,
                 evaluate_lisp,
-                inform_lisp_to_json,
-                lisp_to_json,
+                inform_scheme_to_json,
+                scheme_to_json,
                 inform_json,
                 evaluate_json,
-                inform_json_to_lisp,
-                json_to_lisp
+                inform_json_to_scheme,
+                json_to_scheme
             ],
         )
         .configure(rocket_config)