diff --git a/Makefile b/Makefile index 4d2a811..0c8ed9d 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,7 @@ CD=cd AWK=awk GREP=grep SORT=sort +TEST=test # Config worker_chroot = $(smr_var)/kore_worker @@ -104,13 +105,13 @@ install: $(app_root) $(kmgr_chroot) $(parent_chroot) $(initscript) $(config) smr $(config) : conf/smr.conf $(Q)$(MKDIR) $(conf_path) - $(Q)$(COPY) $< $@ + $(Q)$(TEST) ! -e $@ && $(COPY) $< $@ $(initscript) : packaging/systemd/smr.service $(Q)$(COPY) $< $@ cloc: ## calculate source lines of code in smr - cloc --force-lang="html",etlua --force-lang="lua",luasrc assets Makefile + cloc --force-lang="html",etlua --force-lang="lua",lua src assets Makefile $(app_root): $(Q)$(MKDIR) $(app_root) @@ -153,7 +154,7 @@ $(built_sql): $(app_root)/sql/%.sql : src/sql/%.sql $(Q)$(ECHO) "[copy] $@" $(Q)$(COPY) $^ $@ -$(built_tests) : $(app_root)/spec/% : spec/% $(app_root)/spec +$(built_tests): $(app_root)/spec/% : spec/% $(app_root)/spec $(Q)$(ECHO) "[copy] $@" $(Q)$(COPY) $< $@ @@ -161,15 +162,22 @@ $(app_root)/spec: $(app_root) $(Q)$(MKDIR) $@ $(Q)$(MKDIR) $@/parser_tests -smr.so : $(src_files) conf/build.conf $(asset_files) +smr.so: $(src_files) conf/build.conf $(asset_files) $(Q)$(ECHO) "[build] $@" $(Q)$(KODEV) build -test : $(built) ## run the unit tests +test: $(built) ## run the unit tests $(Q)$(CD) $(app_root) && busted -v --no-keep-going --exclude-tags "slow,todo,working" -cov : $(built) ## code coverage (based on unit tests) +cov: $(built) ## code coverage (based on unit tests) $(Q)$(RM) $(kore_chroot)/luacov.stats.out $(Q)$(CD) $(kore_chroot) && busted -v -c --no-keep-going --exclude-tags slow $(Q)$(CD) $(kore_chroot) && luacov endpoints/ $(Q)$(ECHO) "open kore_chroot/luacov.report.out to view coverage results." + +doc: + rm -rf .trblcache + ~/Programs/trbldoc/trbldoc.sh src + cd .trblcache/built && python3 -m http.server + +.PHONY: doc diff --git a/doc/appendix.md b/doc/appendix.md index 63e6316..b4f6858 100644 --- a/doc/appendix.md +++ b/doc/appendix.md @@ -6,3 +6,4 @@ All other values are considered truethy. In addition, tables may have a metatable that has a `__toboolean` function to implement their own truethyness or falseyness. `false` should be used in places where a boolean is expected, and `nil` should be used otherwise. + diff --git a/doc/hooks.md b/doc/hooks.md index 96715f3..a2ecde2 100644 --- a/doc/hooks.md +++ b/doc/hooks.md @@ -12,3 +12,9 @@ create_user(details :: table) :: boolean ``` Called when a user creates a user account on the site. +``` +authenticate(data :: table) :: number | nil, string +``` +Called when a user attempts to log in. Return a number, userid if the login is successful, or nil and an error message if the login is not successful. By default, smr puts "user" and "passfile" fields into the data table. + + diff --git a/src/lua/addon.lua b/src/lua/addon.lua index da2bb7b..6a84177 100644 --- a/src/lua/addon.lua +++ b/src/lua/addon.lua @@ -1,6 +1,12 @@ --[[ md @name lua/addon +## Addon + +Addons allow you to modify the behavior of smr without modifying the smr +source code. This is intended to make updates easier, and to modularize parts +of smr that are not minimally required. + Addon loader - Addons are either: * A folder with at least two files: - meta.lua - contains addon information @@ -9,8 +15,10 @@ Addon loader - Addons are either: * A sqlite3 database with a table "files" that has at least the columns * name :: TEXT - The filename * data :: BINARY - The file data - And there are at least 2 rows with filenames `meta.lua` and `init.lua` - as described above. Addons should be placed in $SMR_ADDONS, defined in config.lua + +And there are at least 2 rows with filenames `meta.lua` and `init.lua` +as described above. Addons should be placed in {{config/addons_folder}, +defined in `config.lua` The `meta.lua` file is run at worker init time (i.e. it will be run once for each worker), and should return a table with at least the following information diff --git a/src/lua/hooks.lua b/src/lua/hooks.lua index 0d3b461..d9b752e 100644 --- a/src/lua/hooks.lua +++ b/src/lua/hooks.lua @@ -1,13 +1,47 @@ ---[[ +--[[ md +@name lua/hooks + Global functions that smr exposes that can be detoured by addons + +]] + +--[[ md +@name doc/detouring + +# Detouring + +In Lua, functions are given a name, but more generally, they values on a table +, perhaps the global table `_G`, and their names are the keys on the table. +When you want to modify a function that exists either in smr or in other addons +you can **detour** the function by saving a reference to the original function, +and then creating a new function that calls the original, maybe after doing +other work, or modifying the arguments. For example: + + local pages = require("pages") + + -- Get notified when the index page is rendered to the user + local oldindex = pages.index + function pages.index(...) + print("Index page is getting rendered!") + oldindex(...) + end ]] local api = {} --- Called before any request processing. Returning true "traps" the request, and --- does not continue calling smr logic. Well-behaved addons should check for --- "true" from the detoured function, and return true immediately if the check --- succeeds. +--[[ md +@name lua/hooks + +## pre_request + +Called before any request processing. Returning true "traps" the request, and +does not continue calling smr logic. Well-behaved addons should check for +"true" from the detoured function, and return true immediately if the check +succeeds. + +@param req {{http_request}} - The request about to be processed +@returns boolean - If true, further processing is not done on this request. +]] api.pre_request = function(req) end -- Called after smr request processing. Returning true "traps" the request. diff --git a/src/lua/init.lua b/src/lua/init.lua index 7e696c2..4e6321e 100644 --- a/src/lua/init.lua +++ b/src/lua/init.lua @@ -4,6 +4,36 @@ It registers a bunch of global functions that get called from kore when users visit particular pages. See src/smr.c for the names of the public functions. See conf/smr.conf for the data that can be access in each function ]] + +--[[ md +@name lua + +# Lua namespace + +By default, smr will run init.lua defined by smr, and then addons in order, +see {{lua/addon}} for information on how smr loads addons. You can use any +of the modules that ship with smr by including them, and then calling the +functions defined in that module. + +For example, the module {{lua/db}} holdes a reference to the sqlite3 database +that smr uses for data storage. If you addon needs to set up a table and +prepare sql statements for an api endpoint, you might set it up like this: + + local db = require("db") + + local oldconfigure = configure -- Hold a refrence to configure() + function configure(...) -- Detour the configure function + db.sqlassert(db.conn:exec([=[ + CREATE TABLE IF NOT EXISTS foo ( + id INTEGER AUTOINCREMENT PRIMARY KEY + value TEXT + ); + ]=])) + oldconfigure(...) + end + +Be sure to always {{doc/appendix/detourin}} +]] print("Really fast print from init.lua") --Luarocks libraries