From 3d06a48939a8c331903be2a098a119af852e022e Mon Sep 17 00:00:00 2001 From: Robin Malley Date: Thu, 6 Jul 2023 00:42:23 +0000 Subject: [PATCH] More documentation --- spec/author_bio_spec.lua | 55 ++---------------------------- src/libcrypto.c | 27 ++++++++++----- src/libkore.c | 72 ++++++++++++++++++++++++++++++++++++++++ src/lua/db.lua | 11 ++++-- 4 files changed, 101 insertions(+), 64 deletions(-) diff --git a/spec/author_bio_spec.lua b/spec/author_bio_spec.lua index 70a18a4..a703de7 100644 --- a/spec/author_bio_spec.lua +++ b/spec/author_bio_spec.lua @@ -2,7 +2,7 @@ _G.spy = spy local mock_env = require("spec.env_mock") local rng = require("spec.fuzzgen") -describe("smr biography #todo",function() +describe("smr biography",function() setup(mock_env.setup) teardown(mock_env.teardown) it("should allow users to set their biography",function() @@ -59,60 +59,11 @@ describe("smr biography #todo",function() method = "GET", host = username .. ".test.host", path = "/_bio", - cookies = { - session = sessionid - }, + cookies = {session = sessionid}, args = {} } bio_get(edit_bio_req_get) assert(edit_bio_req_get.responsecode == 200) - --[=[ - local paste_req_post = { - method = "POST", - host = username .. ".test.host", - path = "/_paste", - cookies = { - session = sessionid - }, - args = { - title = "post title", - text = "post text", - markup = "plain", - tags = "", - } - } - paste_post(paste_req_post) - for row in db.conn:rows("SELECT COUNT(*) FROM posts") do - assert(row[1] == 1, "Expected exactly 1 post in sample db") - end - local code = paste_req_post.responsecode - assert(code >= 300 and code <= 400, "Should receive a redirect after posting, got:" .. tostring(code)) - assert(paste_req_post.response_headers, "Should have received some response headers") - assert(paste_req_post.response_headers.Location, "Should have received a location in response headers") - local redirect = paste_req_post.response_headers.Location:match("(/[^/]*)$") - local read_req_get = { - method = "GET", - host = username .. ".test.host", - path = redirect, - cookies = { - session = sessionid - }, - args = {} - } - read_get(read_req_get) - local response = read_req_get.response - assert( - response:find([[post title]]), - "Failed to find post title in response." - ) - assert( - response:find('By ' .. username .. ''), - "Failed to find the author name after a paste." - ) - assert( - response:find([[post text]]), - "Failed to find post text in response." - ) - ]=] + assert(edit_bio_req_get.response:find(" +// Used to push "string" = number onto the table at the top of the stack #define LUA_PUSH_CONST(L,a) lua_pushnumber(L,a); lua_setfield(L,-2,#a); +/* md +@name lua/kore +@ref http_request + +### http_request {#http_request} + +An `http_request` userdata logically represents a request that the kore webserver has received. You can get arguments, files uploaded with the request, and respond to the request. The userdata does not have any methods on it. It is backed by a {{ kore_request }} + +*/ + +/* +Checks that the argument at *pos* is a kore_request userdata +*/ struct http_request* luaL_checkrequest(lua_State *L, int pos){ if(!lua_isuserdata(L,pos)){ @@ -25,6 +39,25 @@ luaL_checkrequest(lua_State *L, int pos){ return lua_touserdata(L,pos); } +/* md +@name lua/kore + +### http_response + +Sends a response to the request given. After this method is called, calls to other methods that accept a request userdata may not work correctly (the data may have been garbage collected). + +Parameters: +0. request - {{ http_request }} - The request to serve +0. errcode - {{ lua/number }} - The http error code. See [http error codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for error codes generally accepted by web browsers, but you can return any number here and kore will attempt to send it. +0. data - {{ lua/string }} | {{ lua/nil }} - The data to return with the request. If `nil` is passed, the request's return will have an empty body. + +No returns. + +Example: + +TODO + +*/ /* http_response(request::userdata, errcode::number, (data::string | nil)) */ @@ -198,6 +231,24 @@ lhttp_response_co(lua_State *L){ return 0; } +/* md +@name lua/kore + +### http_method_text + +Gets the http method the request was called with (ex `GET`, `POST`, ect.) + +Parameters: + +0. request - {{ http_request }} - The request to get the method string off of. + +Returns: + +0. method - {{ lua/string }} - The string from the request + +Example: +TODO +*/ /* http_method_text(request::userdata)::string */ @@ -210,6 +261,27 @@ lhttp_method_text(lua_State *L){ return 1; } +/* md +@name lua/kore + +### http_request_get_path + +Gets the path from the end of the url. + +Parameters: + +0. request - {{http_request}} - The request to get the path from. + +Returns: + +0. path - {{ lua/string }} - The path part of the url. + +Example: + + local req = ... + print(http_request_get_path(req)) + +*/ /* http_request_get_path(request::userdata)::string */ diff --git a/src/lua/db.lua b/src/lua/db.lua index 6b5a322..b1e3ff2 100644 --- a/src/lua/db.lua +++ b/src/lua/db.lua @@ -69,7 +69,8 @@ Parameters: Returns: -0. err - {{lua/number}} - The error code returned from running the statement. Will be `lsqlite.OK` on success, see {{lsqlite/errcodes}} +0. err - {{lua/number}} - The error code returned from running the statement. +Will be `lsqlite.OK` on success, see {{lsqlite/errcodes}} Example: @@ -163,8 +164,10 @@ with better error reporting. Parameters: 0. stmnt - {{lsqlite/stmnt}} - The prepared statement from {{sqlite/db/prepare}} -0. call - {{lua/string}} - Literal string, options are `bind` for most types, or `bind_blob` for strings that may contain embedded nulls -0. position - {{lua/number}} - The argument position to bind to, does not support named parameters +0. call - {{lua/string}} - Literal string, options are `bind` for most types, +or `bind_blob` for strings that may contain embedded nulls +0. position - {{lua/number}} - The argument position to bind to, +does not support named parameters 0. data - Any - the data to bind Returns nothing @@ -210,6 +213,8 @@ end --[[ md +@name lua/db + ### db.close() Closes the database connection. Not called during normal operation, used to