From 545a33aac755ede43e2509d0492851765d3fd832 Mon Sep 17 00:00:00 2001
From: gennyble <gen@nyble.dev>
Date: Wed, 2 Apr 2025 06:31:08 -0500
Subject: add smalldog docs

---
 smalldog/README.md  | 43 +++++++++++++++++++++++++++++++++++++++++++
 smalldog/src/lib.rs | 10 +++++-----
 2 files changed, 48 insertions(+), 5 deletions(-)
 create mode 100644 smalldog/README.md

(limited to 'smalldog')

diff --git a/smalldog/README.md b/smalldog/README.md
new file mode 100644
index 0000000..87d3416
--- /dev/null
+++ b/smalldog/README.md
@@ -0,0 +1,43 @@
+smalldog
+
+a crate for safely working with corgi's cgi module system.
+
+module's are loaded in a new thread at the time of request.
+
+if you want to build a module in C, these structs will be of use:
+```c
+// In Rust this is interpreted as a fixed size, 2-element array of char*
+// but i cannot get C to like that kind of at all. sorry.
+struct pair {
+	char *name;
+	char *value;
+};
+
+// The request from corgi. body may be null if one was not sent.
+struct request {
+	u64_t headers_len;
+	struct pair *headers;
+	u64_t body_len;
+	u8_t *body;
+};
+
+// The request your module should return to corgi
+struct response {
+	u16_t status;
+	u64_t headers_len;
+	struct pair *headers;
+	u64_t body_len;
+	u8_t *body;
+};
+```
+
+as well as that, there are two functions that corgi expects to exist and will call.
+
+`struct response *handle(struct request*);`  
+this function is called after the module is loaded. here you should process the
+request and send back a response. be sure to keep track of any allocations so
+you can clean them up later.
+
+`void cleanup(struct response*);`  
+this is where you clean up, later. function is called after corgi copies all
+required data to an internal structure. free memory here.
\ No newline at end of file
diff --git a/smalldog/src/lib.rs b/smalldog/src/lib.rs
index 27b0140..1691588 100644
--- a/smalldog/src/lib.rs
+++ b/smalldog/src/lib.rs
@@ -8,19 +8,19 @@ pub mod ffi {
 
 	#[repr(C)]
 	pub struct ModuleRequest<'req> {
-		pub headers_len: ffi::c_ulong,
+		pub headers_len: u64,
 		pub headers: *const [*const ffi::c_char; 2],
-		pub body_len: ffi::c_ulong,
+		pub body_len: u64,
 		pub body: *const u8,
 		pub _phantom: PhantomData<&'req u8>,
 	}
 
 	#[repr(C)]
 	pub struct ModuleResponse {
-		pub status: ffi::c_ushort,
-		pub headers_len: ffi::c_ulong,
+		pub status: u16,
+		pub headers_len: u64,
 		pub headers: *const [*const ffi::c_char; 2],
-		pub body_len: ffi::c_ulong,
+		pub body_len: u64,
 		pub body: *const u8,
 	}
 }
-- 
cgit 1.4.1-3-g733a5