plugin_api.md

Constants

• _GOCHAN_VERSION
  • The version string of the running Gochan server

Modules

The following are modules that can be loaded via require("modulename"). See ./examples/plugins/ for usage examples.

External modules

• async
• filepath
• json
• strings

config

• config.system_critical_config()
  • Returns the SystemCriticalConfig
• config.site_config()
  • Returns the SiteConfig
• config.board_config(board string)
  • Returns the BoardConfig for the given board, or the default BoardConfig if board is an empty string

events

• events.register_event(events_table, handler_func)
  • Registers handler_func for the events in events_table. If any arguments are passed to the event when it is triggered, it will be sent to handler_func.
• events.trigger_event(event_name string, data...)
  • Triggers the event registered to event_name and passes data (if set) to the event handler.

gclog

• gclog.info_log()
  • Creates and returns a zerolog Event object with an info level.
• gclog.warn_log()
  • Creates and returns a zerolog Event object with a warning level.
• gclog.error_log([error_message string])
  • Creates and returns a zerolog Event object for the error log. If a string is used as the argument, it is used as the error message.

gcsql

• gcsql.query_rows(query string, args...)
  • Returns a Rows object for the given SQL query and an error if any occured, or nil if there were no errors. args if given will be used for a parameterized query.
• gcsql.execute_sql(query string, args...)
  • Executes the SQL string query with the optional args as parameters and returns a Result object and an error (or nil if there were no errors)
• gcsql.scan_rows(rows, scan_table)
  • scans the value of the current row into scan_table and returns an error if any occured, or nil if there were no errors.

gctemplates

• gctemplates.load_template(files...)
  • Loads the given file paths into a Template, using the base filename as the name, and returns the template and an error if one occured.
• gctemplates.parse_template(template_name string, template_data string)
  • Calls gctemplates.ParseTemplate with the given template name and Go template data, and returns a Template and an error object (or nil if there were no errors).

geoip

• geoip.country_name(abbr string) (string, error)

  • Returns the country name, given its abbreviation, and an error if any occured

• geoip.register_handler(name string, handler table) error

  • Calls posting.RegisterGeoIPHandler with the given handler info and returns an error if any occured. The table is expected to have the following fields/values:

Key	Type	Explanation
init	func(options map[string]any) error	The function to initialize the GeoIP handler with options. If it needs no initialization, the function can return null
get_country	func(request http.Request, board string, errEv zerolog.Event) geoip.Country, error	The function to get the requesting IP's country, returning it and any errors that occured
close	func() error	The function to close any network or file handles, if any were opened, returning an error if any occured

manage

• manage.ban_ip(ip string, duration string, reason string, staff string|int, options table)
  • Bans the given IP for the given duration and gets other optional ban data from the options table below

Key	Type	Explanation
board	string|int|nil	The board directory or ID that the IP will be banned from. If this is nil or omitted, it will be a global ban
post	int	The post ID
is_thread_ban	bool	If true, the user will be able to post but unable to create threads
appeal_after	string	User can appeal after this duration. If unset, the user can appeal immediately.
appealable	bool	Sets whether or not the user can appeal the ban. If unset, the user is able to appeal.
staff_note	string	A private note attached to the ban that only staff can see

• manage.register_manage_page(action string, title string, perms int, wants_json int, handler func(writer, request, staff, wants_json, info_ev, err_ev))
  • Registers the manage page accessible at /manage/action to be handled by handler. See manage.RegisterManagePage for info on how handler should be used, or registermgmtpage.lua for an example

serverutil

• serverutil.minify_template(template, data_table, writer, media_type)
  • Calls serverutil.MinifyTemplate with the given template object, data_table (as variables passed to the template), writer, and media_type. See registermgmtpage.lua for an example

uploads

• uploads.register_handler(ext string, function(upload, post, board, filePath, thumbPath, catalogThumbPath, infoEv, accessEv, errEv))
  • Registers a function to be called for handling uploaded files with the given extension. See pdf_thumbnail.lua for a usage example.
• uploads.get_thumbnail_ext(upload_ext string)
  • Returns the configured (or built-in) thumbnail file extension to be used for the given upload extension
• uploads.set_thumbnail_ext(upload_ext string, thumbnail_ext string)
  • Sets the thumbnail extension to be used for the given upload extension

url

• url.join_path(base string, ext...string)
  • Returns a string representing a URL-compatible path, with ext joined to base
• path_escape(path string)
  • Returns a string with any special characters escaped to be compatible with URL paths
• path_unescape(escaped string)
  • Attempts to unescape the given string, and returns the result and any errors (or nil if it was successful)
• query_escape(query string)
  • Escapes the given string so that it can be used in a URL query
• query_unescape(escaped string)
  • Attempts to unescape the given query-escaped string, and returns the result and any errors (or nil if it was successful)

Events

This is a list of events that gochan may trigger at some point and can be used in the plugin system.

• db-connected

  • Triggered after gochan successfully connects to the database but before it is checked and initialized (db version checking, provisisioning, etc)

• db-initialized

  • Triggered after the database is successfully initialized (db version checking, provisioning, etc)

• db-views-reset

  • Triggered after the SQL views have been successfully reset, either immediately after the database is initialized, or by a staff member

• incoming-upload

  • Triggered by the gcsql package when an upload is attached to a post. It is triggered before the upload is entered in the database

• message-pre-format

  • Triggered when an incoming post or post edit is about to be formatted, event data includes the post object and the HTTP request

• reset-boards-sections

  • Triggered when the boards and sections array needs to be refreshed

• shutdown

  • Triggered when gochan is about to shut down, in main() as a deferred call

• startup

  • Triggered when gochan first starts after its plugin system is initialized. This is (or at least should be) only triggered once.

• upload-saved

  • Triggered by the posting package when an upload is saved to the disk but before thumbnails are generated.