claude go reimplement

2026-10-26 20:30:43 -07:00
1 parent 4bcb924158
commit f523c79618
@@ -4,6 +4,9 @@ King James Version web API is a machine and human callable service to
 query the King James Bible and provides useful features, such as random
 verses and a quote of the day.

+It is a single dependancyless program (kjv-api) and its companion sqlite3
+database (kjv.db). Those two files are the entire distribution.
+

 EXTERNAL DATA
 =============
@@ -11,79 +14,207 @@ The software uses a sqlite3 database as external data dependancy, saved locally
 and modified to remove false Bible translations (included)
 https://github.com/scrollmapper/bible_databases

-For software dependancies see INSTALL.txt
+kjv.db also holds everything else the program serves, so there is nothing else
+to copy next to it: the pages, scripts and styles (the assets table), the 1828
+Webster dictionary, the spellchecking word list, users' reading plans and
+shortcodes, and the logs.


 INSTALLATION
 ============
-See INSTALL.TXT
+Nothing needs to be installed to run it: no runtime, no packages, no root.
+There are two ways to run it, pick one. Both start from the dist folder:
+  kjv-api              - the program
+  kjv.db               - its database
+  kjv-api.service      - systemd user service, for way 2
+  kjv-api.nginx.conf   - nginx reverse proxy site, for way 2
+  kjv-api.apache.conf  - the same for apache, if you use that instead
+Get the two files in it by building them ($ make dist, see BUILDING) or from
+whoever gave them to you.
+
+1. Run it locally, just to use it or try it
+-------------------------------------------
+$ dist/kjv-api
+Then browse to http://127.0.0.1:1611 , Ctrl-C stops it. That's all.
+It uses the kjv.db next to it, which keeps your reading plans, shortcodes and logs
+(make dist replaces dist/kjv.db with a fresh one). On another port, for example
+when the service (way 2) already has 1611 on this machine:
+$ dist/kjv-api -addr 127.0.0.1:1612
+
+2. Install it as a persistent service behind nginx
+--------------------------------------------------
+It runs as a systemd user service under your own account on 127.0.0.1:1611,
+and nginx forwards your domain to it. There is no root service and no special user.
+
+  a. Put the program and database in ~/kjv-api, and start the service:
+     $ mkdir -p ~/kjv-api ~/.config/systemd/user
+     $ cp dist/kjv-api dist/kjv.db ~/kjv-api/
+     $ cp dist/kjv-api.service ~/.config/systemd/user/
+     $ systemctl --user daemon-reload
+     $ systemctl --user enable --now kjv-api
+     $ sudo loginctl enable-linger $USER     # keeps it running when you log out, starts it at boot
+     $ curl 127.0.0.1:1611/random            # a Bible verse in json means it works
+
+  b. Point nginx at it (change example.com in the file to your domain first):
+     $ sudo cp dist/kjv-api.nginx.conf /etc/nginx/sites-available/kjv-api
+     $ sudo ln -s /etc/nginx/sites-available/kjv-api /etc/nginx/sites-enabled/
+     $ sudo nginx -t && sudo systemctl reload nginx
+     $ sudo certbot --nginx -d example.com   # https, optional but recommended
+     Already have a site on that domain? Copy just the location block from the file into it.
+
+  Settings: optional, see the environment variables below. Put them in
+  ~/kjv-api/kjv-api.env (one NAME=value per line), chmod 600 it, and
+  systemctl --user restart kjv-api.
+
+  Updating: replace only the program, never kjv.db (it holds your users' reading
+  plans and shortcodes, and your logs). From the source folder:
+     $ make dist
+     $ install -m 755 dist/kjv-api ~/kjv-api/kjv-api
+     $ ~/kjv-api/kjv-api import-assets -db ~/kjv-api/kjv.db assets   # only if pages changed
+     $ systemctl --user restart kjv-api
+
+  Logs: journalctl --user -u kjv-api -f
+    or: ~/kjv-api/kjv-api logs -db ~/kjv-api/kjv.db -n 100
+
+  Uninstall: systemctl --user disable --now kjv-api, then delete ~/kjv-api,
+  ~/.config/systemd/user/kjv-api.service and the nginx site.

 USAGE
 =====
-The program may be invoked by running kjv-api.sh in a non-root account, or via
-systemd daemon process in a non-root account.
-Alternately for testing, the program may be run on another port by running:
-$ uwsgi_python3 --http-socket <listen address>:<port> --wsgi-file /opt/kjv-api/app.py --callable app
-or by executing kjv-api-test.sh which will listen on 0.0.0.0:1612
+It only ever listens on localhost (127.0.0.1:1611 unless told otherwise), it is
+meant to sit behind a reverse proxy. Asking it to listen on any other address is refused.
+For development, scripts/kjv-api-test.sh builds it, copies the database, and
+listens on 127.0.0.1:1612

 Visiting the base directory will show the user-facing documentation via web browser or cURL.

-When testing or doing a deployment, the data directory must be owned by whatever user is
-running the program in order to prevent a sqlite3.OperationalError for writing to a "readonly"
-database.
+Changing a page, script, style or data file means editing it in the source tree
+and loading it into the database again, then restarting the program:
+$ ./kjv-api import-assets -db kjv.db assets
+
+The logs are in the database, there is no log rotation but the program deletes
+lines older than 90 days when it starts:
+$ ./kjv-api logs -db kjv.db -n 100
+$ sqlite3 kjv.db "select * from logs where level = 'ERROR'"
+When run by systemd the same lines also go to the journal (journalctl --user -u kjv-api),
+and KJV_LOG_STDERR=1 does that outside of systemd.
+
+When testing or doing a deployment, the directory holding kjv.db must be owned by
+whatever user is running the program (sqlite3 writes its journal beside the
+database), otherwise reading plans, shortcodes and logs will not be saved.
+
+Optional environment variables
+- KJV_DB - path to kjv.db instead of the -db flag
+- KJV_ADDR - localhost address to listen on instead of the -addr flag
+- KJV_SECRET_API_KEY - the token POST /natural expects, and the bearer token the /seqreport and
+  /screport listings need (without it those two do not exist).
+- KJV_LOG_STDERR - set to 1 to also print the log lines to stderr (automatic under systemd)
+- KJV_SEMANTIC_ADDR - where the semantic search service listens, default localhost:1613
+- KJV_SERMON_DB - path to the separate sermon database. Without it the sermon
+  endpoints answer 503.
+
+BUILDING
+========
+Only the machine that compiles needs anything: go 1.26 or newer, and make (built
+and tested with go 1.27.3, get it from https://go.dev/dl/ or your package manager).
+The sqlite3 driver (modernc.org/sqlite) is pure Go, no C compiler needed, and go
+downloads it the first time it builds.
+$ make build  builds bin/kjv-api
+$ make dist   builds dist/kjv-api and dist/kjv.db, the two files to distribute
+$ make test   go vet, and any tests
+Optional: sqlite3 (the command line tool) for looking at the logs and database.

 CONTENTS
 ========
 .
-├── app.py - main program
-├── data
-│   ├── 1828_Webster_KJV.json - Dictionary
-│   ├── kjv.aff - KJV Spellchecking Description file (hunspell)
-│   ├── kjv.db - KJV sqlite3 database
-│   └── kjv.dic - KJV Spellchecking dictionary file (hunspell)
-│   └── seq.db - Sqlite3 Database with user's ids for sequenced scripture
-│   └── shortcodes.db - Sqlite3 Database with saved shortcodes for scripture groups.
-├── favicon.ico
-├── html
-│   ├── dictionary.html - dictionary search landing page /define
-│   ├── find.html - unified search bar landing page /find
-│   ├── navbar.html - navigation bar added programatically to rich results
-│   ├── heaven.html - Bible way to heaven, static page /salvation
-│   ├── on_reading_bible.html - Introduction on good reading practices
-│   ├── index.html - / landing page with unified search bar
-│   ├── reader.html - not yet implemented Bible browser end point
-│   ├── reading_plan.html - not yet implemented Bible reading plan generator
-│   ├── response.html - Template for rich verse responses
-│   ├── search.html - Bible keyword search landing page /search
-│   ├── search_bar.html - Unused
-│   ├── show.html - Bible verse search landing page /show
-│   ├── seq.html - Bible sequential verse landing page /seq
-│   └── votd.html - Matty's test VOTD rich landing page
-├── install
-│   ├── apache.site.conf.example - example installation configuration
-│   └── kjv-api.service - example systemd service file
-├── INSTALL.txt - installation instructions
-├── logs - log folder (populated at runtime - there is NO log rotation)
-├── js
-│   └── collapsible.js - js for the definition drop-down menu used in unified search
-├── kjv-api.sh - runs uwsgi flask app on port 1611
-├── kjv-api-test.sh - runs uwsgi flask app on port 1612
-├── README.txt - This document
-├── styles
-│   ├── collapsible.css
-│   ├── header.css
-│   ├── fonts
-│   │   ├── Arizonia-Regular.ttf
-│   │   └── Parisienne-Regular.ttf
-│   ├── human_readable.css
-│   ├── search_rich.css
-│   └── votd.css
-└── tools
-    └── av1611_dictionary_scraper.py - builds a dictionary json for the 1828 dictionary
-    └── sanity_check.py - Integrated during runtime and also as endpoint testing when run alone.
-    └── search_keywords.txt - endpoint testing queries
-    └── sanity_results.txt - results of running sanity_check.py as a standalone
+├── cmd
+│   └── kjv-api
+│       └── main.go - command line: run the server, import-assets, logs
+├── internal
+│   └── kjv - the program, one package
+│       ├── server.go - startup, localhost listener, routes
+│       ├── app.go - loads the assets from the database, builds the rich page pieces and verse rendering
+│       ├── pages.go - /show /find /search /define /random /votd
+│       ├── refs.go - reference resolver ("1 jn 3.16", "II Kings 2:1-4", "song of songs 2")
+│       ├── state.go - /seq /plan and shortcodes, saved in the database
+│       ├── sermons.go - sermon database and semantic search endpoints, optional
+│       ├── store.go - the kjv.db queries and the Bible held in memory
+│       ├── assets.go - import-assets, putting the files in assets/ into the database
+│       ├── logdb.go - logs saved in the database
+│       ├── spell.go - spellchecking suggestions from the word list
+│       ├── difflib.go - fuzzy book name matching
+│       └── mt.go - the random number generator that picks the verse of the day
+├── db
+│   └── kjv.db - KJV sqlite3 database, the start of the companion database
+├── assets - everything that gets loaded into kjv.db by import-assets
+│   ├── data
+│   │   ├── 1828_Webster_KJV.json - Dictionary
+│   │   ├── kjv.aff - KJV Spellchecking Description file
+│   │   ├── kjv.dic - KJV Spellchecking dictionary file
+│   │   └── *.json - book descriptions, chapter summaries, search synonyms and variants
+│   ├── html
+│   │   ├── dictionary.html - dictionary search landing page /define
+│   │   ├── find.html - unified search bar landing page /find
+│   │   ├── navbar.html - navigation bar added programatically to rich results
+│   │   ├── chapter_nav.html - previous/next chapter bar
+│   │   ├── heaven.html - Bible way to heaven, static page /salvation
+│   │   ├── on_reading_bible.html - Introduction on good reading practices
+│   │   ├── index.html - / landing page with unified search bar, the program fills in the book lists
+│   │   ├── plan.html - Bible reading plan setup /plan
+│   │   ├── saved.html - favorites, definitions and cross references kept in the browser /saved
+│   │   ├── response.html - Template for rich verse responses
+│   │   ├── search.html - Bible keyword search landing page /search
+│   │   ├── search_bar.html - Unused
+│   │   ├── show.html - Bible verse search landing page /show
+│   │   ├── seq.html - Bible sequential verse landing page /seq
+│   │   └── votd.html - Matty's test VOTD rich landing page
+│   ├── js
+│   │   ├── collapsible.js - js for the definition drop-down menu used in unified search
+│   │   └── book_suggest.js, shortcode.js, verse_menu.js
+│   ├── static
+│   │   └── favicon.svg, favicon.ico
+│   ├── styles
+│   │   ├── collapsible.css
+│   │   ├── header.css
+│   │   ├── fonts
+│   │   │   ├── Arizonia-Regular.ttf
+│   │   │   └── Parisienne-Regular.ttf
+│   │   ├── human_readable.css
+│   │   ├── search_rich.css
+│   │   └── votd.css
+│   └── kjv_fe.html - /fe frontend page
+├── dist - what gets deployed, see INSTALLATION
+│   ├── kjv-api, kjv.db - built by make dist (not kept in git)
+│   ├── kjv-api.service - systemd user service, port 1611
+│   ├── kjv-api.nginx.conf - nginx reverse proxy site
+│   └── kjv-api.apache.conf - apache reverse proxy site
+├── scripts
+│   ├── kjv-api.sh - builds if needed and runs the program on localhost port 1611
+│   └── kjv-api-test.sh - builds and runs the program on a copy of the database on port 1612
+├── tools
+│   ├── av1611_dictionary_scraper.py - builds a dictionary json for the 1828 dictionary
+│   ├── sanity_check.py - Endpoint testing, run alone against a running instance (needs python3-requests)
+│   └── search_keywords.txt - endpoint testing queries
+├── doc
+│   ├── openapi.yaml
+│   └── notes.txt
+├── Makefile - make, make dist, make test
+├── go.mod, go.sum
+└── README.txt - This document

 AUTHOR
 ======
-Copyright Tyler R Dinsmoor & Matty Sneederson 2023
+Copyright Tyler R Dinsmoor & Matty Sneederson 2022-2026
+Reimplemented in Go by demon machine claude.
+
+
+SECURITY
+========
+- Listens on localhost only, and refuses any other address.
+- The user service runs as your account, so it can read and write whatever you can. For more
+  separation, make an account just for it (sudo useradd -m kjv; sudo loginctl enable-linger kjv)
+  and do step 2a logged in as that account.
+- Reading plan ids and shortcodes are random but they are the only secret; anyone holding a plan id can
+  move that plan. Making new ones is rate limited per visitor (by the X-Real-IP the proxy sends,
+  the nginx and apache files do). Plans unused for 90 days are deleted.
+- Please report anything you find to the author.