gas-stack/doc/gas-stack.md

# GAS stack

## Concepts

- explict `schema.sql`
- solid-state applications
	- no Docker
		- https://git.tnd.gg/tnd/remichat/pulls/4#issuecomment-1218
	- no environment split ("prod" vs "dev")
		- environment distinctions are provided by scripts that call the application, not by the application
		- try to avoid config files-- use shell scripts that pass flags instead
		- put all the config variable values for a certain environment in that environment's runner context:
			- values that are specific to Docker setups should go in docker-compose
			- values that are for non-docker dev, maybe in .env or a runner shell script, or something like this
			- assume that config values are finalized (i.e., don't need to be checked configVal == "" ? "default" : configVal) as high in the stack as possible (and also ensure this is the case). Ideally, vite.config.ts and onward already shouldn't need to do any val || "default" checking, and can simply accept env.PORT_NUMBER or env.IS_LOGGING_ENABLED as-is (or at most, parsing string->int, etc).
			- https://git.tnd.gg/tnd/remichat/pulls/38#issuecomment-1645
	- no frontend-backend separation (CORS)
	- minimal config
		- avoid cascading configs and multiple layers of defaults (e.g., `{ XYZ: "prefix" + (upperlayer.XYZ || "DefaultValue"), ... }`)

- subcommands executables
	- scriptable applications: anything that the application can do, can be done via command line (i.e., avoid web-only operations)
	- config is passed as command-line args
	- avoid config env-vars (magical)
	- shell scripts as glue code

- sample data
	- https://git.tnd.gg/tnd/remichat/pulls/65#issuecomment-2035

- `ops` directory

### Borrowed from Ruby On Rails

- Convention Over Configuration
- scaffolding (code generators)
- database migration system
- focus on testing
- ORM-like affordances (but not actually using an ORM)

## Vendoring vs Package Management vs In-Sourcing

Dependencies are technical debt.  See [Loris Cro's talk about "How To Write Better Software with Zig"](https://www.youtube.com/watch?v=AEybWzeAkho).

## Scaffolding

Scaffolding is not boilerplate code, generated code, or library code.  It's *starter code* which is *intended to be modified* as needed.

Library code is provided as a pre-made, off-the-shelf solution.  If your problem is exactly the one the library is intended to solve, and the library does a good job, you should use it.  Lots of big stuff is like this; nobody implements their own HTTP server or SQL engine as part of an application, because the domain is big, stable and standardized.  It makes perfect sense to use libraries for this.

Boilerplate code and generated code (the latter being a common solution to the former) are usually indicators of bad abstractions.  If there's truly something that needs to be done exactly the same way by rote, every time, then there should be a reusable library for it-- or maybe you're even using the wrong programming language.

Scaffolding isn't either of those, because scaffolding is intended to be *changed*.  It's just a starting point as you flesh out your ideas.

Consider [this parable](https://rcrowley.org/2022/rails-django-parable.html) comparing Rails and Django on their initial setup and tutorial.  The analogy isn't perfect, but his claim is basically that the original Rails official tutorial left you with a tiny app with almost on code and a huge amount of functionality; but since all the functionality was invisible "magic" provided by Rails, as soon as you want something custom, you're nearly starting from scratch'.  By comparison, the Django tutorial produces a large amount of code which makes the abstractions explicit.  The author refers to all those extra lines of code as "footholds", from which you can start working.

Scaffolding *begins* as generic boilerplate, but evolves as your application logic becomes more custom and requirements change.  One piece of scaffolded code might never change, because the scaffolding was good enough; another piece might be tweaked over time, as you add more to it (or remove parts you don't need); and another piece might change so much that no traces of the original scaffolding existed.  One app could contain all three of these.

Scaffolding is intended to make "in-sourcing" your code easier, by getting you to something bare-bones-but-working faster.

## Dynamic vs Static linking

TODO: write about this and why it matters for the GAS stack


## SQLite and ROWID

Tables must be EITHER:
- `rowid integer primary key` as first column declaration; OR
- `without rowid`, i.e., a clustered index

Other primary key and rowid settings are supported by SQLite, but NOT by Gas Stack:
- implicit `rowid`
- alternate `integer primary key` column, i.e., rowid alias
- non-rowid `primary key` that isn't a clustered index (note that SQLite doesn't actually support this, it just pretends to; the declared `primary key` in this case is just a regular unique index)

This is enforced by the Gas Stack schema linter, and cannot be configured.  Other Gas Stack schema tools assume one of these arrangements, and will not work right if it's not followed.

## What not to do

- "scripts" folder
- "bin" with shell scripts in it
- using HTTP PUT or PATCH

## App structure

- pkg/
	- db/
		- schema.sql
		- db_connect.go (migrations, versions and associated funcs, sql_schema, DBCreate, DBConnect)
		- db_connect_test.go
	- test_utils/
		- db_setup.go
- cmd/
	- main.go (parameterize DB_FILENAME)
- doc/
- sample_data/
	- mount.sh
	- seed.sql
	- data/
- .github/
	- workflows/
		- build.yml
- .gitignore (sample_data/data)
- .golangci.yaml
- README.md
- ARCHITECTURE.md


gas init:
	- git init
	- go mod init
	Params:
		- omit sqlite
		- omit github workflow
		- database filename
		- go module name
		- include HTTP?  (pkg/web, templ)
		- data directory or just db file

gas generate_boilerplate [db-table-name]:
	- struct
	- Save function
	- Get[Type]ByID function

gas generate-web
	- install templ
	- echo "*_templ.go" >> .gitignore
	- pkg/web
	- server.go
	- middlewares.go

	- web/
		- static/
			- vendor/
			- styles.css
		- tpl/
		- server.go
		- middlewares.go
		- static.go


gas generate-subcommand

Considerations:
- godoc

# Methodologies

- Timestamp type: store dates and times as int64 (unix millis)
- code tags: TODO, XXX, WTF, DUPE tags
- `go test -tags integration` for integration testing (slow tests)
- cobra commands
- sqlx
- :memory: databases for testing
- go-chi router

- No docker-compose