README
¶
Server Starter
dev dependencies
The following tools are prerequisites for development work:
- go 1.21
- docker && docker-compose
- wire for dependency management
- make for task running
- sqlc for generating database code
- gci for sorting imports
- tagalign for aligning struct tags
- terraform for deploying/formatting
- cloud_sql_proxy for production database access
- fieldalignment (
go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest)
dev setup
It's a good idea to run make test lint integration_tests before commits.
running the server
- clone this repository
- run
make dev - http://localhost:8000/
features
for users
This service, out of the box, supports:
- self-service user signup
- users can be associated with a group of users (called an account)
- users can define a default account
- users can sign up with an invitation token that will immediately associate them with a given account
- users have RBAC permissions associated with their accounts and the base service
- users can enable two factor verification
- users can rotate their two factor secret
- users can change their password, avatar, and details
- users can reset passwords if they forget them
- users can verify their email address
- account admins can change details about their account
- account admins can invite users to their accounts
- service admins can create settings
- users can create configurations for these settings
- users can create webhooks for events related to their accounts
- webhooks are executed asynchronously
- all data changes are published to an event queue
- this can be hooked into to do things like send confirmation emails
- user notifications support
- notifications can be arbitrarily created by admins, or created in the aforementioned async flow
- oauth2 client support
- service admins can create oauth2 clients for users to authenticate with
- Terraform code for deploying service to GCP
external services supported
- Stripe support
- abstracted such that you could support an alternative payment provider (I just haven't found a better one than Stripe)
- analytics support
- support for Segment, Rudderstack, and Posthog
- search support
- support for Algolia and Elasticsearch
- users are automatically indexed into a search engine provider of your choosing
- trivial to add other data types to other indices
- managed email service support
- feature flag support
- support for LaunchDarkly and Posthog
- message queue support
- object storage support
- cache support
- support for in-memory and Redis
code features
- full unit tests for every package
- full service API client
- integration tests that spin up the full service against a proper database using the aforementioned API client
- generated sqlc queries
- generated configuration files
- CI steps that validate generated files
- CI steps that test on every push to a PR
infrastructure
flowchart LR
APIServer("API Server")
PublicInternet("Public Internet")
Sendgrid("Sendgrid")
Segment("Segment")
Algolia("Algolia")
Cron("GCP Cloud Scheduler")
DataChangesWorker("Data Changes Worker")
OutboundEmailerWorker("Outbound Emailer")
SearchDataIndexSchedulerWorker("Data Index Scheduler")
SearchDataIndexerWorker("Search Data Indexer")
PublicInternet-->APIServer
Cron-->SearchDataIndexSchedulerWorker
DataChangesWorker-->OutboundEmailerWorker
DataChangesWorker-->SearchDataIndexerWorker
SearchDataIndexSchedulerWorker-->SearchDataIndexerWorker
SearchDataIndexerWorker-->Algolia
APIServer-->DataChangesWorker
DataChangesWorker-->Segment
OutboundEmailerWorker-->Segment
OutboundEmailerWorker-->Sendgrid
Algolia-->APIServer
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
services/api/http
Command server is the main application that runs an instance of the service
|
Command server is the main application that runs an instance of the service |
|
tools/gen_configs
Command gen_configs generates configuration files in the local repository, configured via the precise mechanism that parses them to guard against invalid configuration
|
Command gen_configs generates configuration files in the local repository, configured via the precise mechanism that parses them to guard against invalid configuration |
|
functions/data_changes
Module
|
|
|
functions/outbound_emailer
Module
|
|
|
functions/search_indexer
Module
|
|
|
internal
|
|
|
authentication
Package authentication provides functions and structures to facilitate salting and authenticating passwords, as well as validating TOTP tokens.
|
Package authentication provides functions and structures to facilitate salting and authenticating passwords, as well as validating TOTP tokens. |
|
capitalism/stripe
Package stripe provides Stripe functionality.
|
Package stripe provides Stripe functionality. |
|
config
Package config provides configuration structs for every service
|
Package config provides configuration structs for every service |
|
database
Package database provides interface abstractions for interacting with relational data stores
|
Package database provides interface abstractions for interacting with relational data stores |
|
database/postgres
Package postgres provides an interface for writing to a Postgres instance.
|
Package postgres provides an interface for writing to a Postgres instance. |
|
encoding
Package encoding provides HTTP response encoding abstractions
|
Package encoding provides HTTP response encoding abstractions |
|
encoding/mock
Package mockencoding provides mockable implementations of every interface defined in the outer encoding package.
|
Package mockencoding provides mockable implementations of every interface defined in the outer encoding package. |
|
identifiers
Package identifiers is a handy place to request a new string identifier from.
|
Package identifiers is a handy place to request a new string identifier from. |
|
observability/tracing/cloudtrace
Package cloudtrace provides common functions for attaching values to trace spans
|
Package cloudtrace provides common functions for attaching values to trace spans |
|
observability/tracing/oteltracehttp
Package oteltracehttp provides common functions for attaching values to trace spans
|
Package oteltracehttp provides common functions for attaching values to trace spans |
|
observability/utils
Package o11yutils offers observability utility functions.
|
Package o11yutils offers observability utility functions. |
|
pkg
Package pkg is a holder for other, miscellaneous packages that aren't intrinsically linked to functionality.
|
Package pkg is a holder for other, miscellaneous packages that aren't intrinsically linked to functionality. |
|
pkg/cryptography/encryption
Package cryptography contains the interfaces and implementations for encrypting and decrypting data.
|
Package cryptography contains the interfaces and implementations for encrypting and decrypting data. |
|
pkg/cryptography/encryption/aes
Package aes contains the interfaces and implementations for encrypting and decrypting data.
|
Package aes contains the interfaces and implementations for encrypting and decrypting data. |
|
pkg/cryptography/encryption/mock
Package encryptionmock contains the interfaces and implementations for encrypting and decrypting data.
|
Package encryptionmock contains the interfaces and implementations for encrypting and decrypting data. |
|
pkg/cryptography/encryption/salsa20
Package salsa20 contains the interfaces and implementations for encrypting and decrypting data.
|
Package salsa20 contains the interfaces and implementations for encrypting and decrypting data. |
|
search
Package search defines an interface for a search index management structure
|
Package search defines an interface for a search index management structure |
|
search/algolia
Package algolia provides an interface-compatible wrapper around the algolia indexer
|
Package algolia provides an interface-compatible wrapper around the algolia indexer |
|
search/elasticsearch
Package elasticsearch provides an interface-compatible wrapper around the elasticsearch indexer
|
Package elasticsearch provides an interface-compatible wrapper around the elasticsearch indexer |
|
search/indexing
Package indexing contains code specific to the service that interacts with search indices generically.
|
Package indexing contains code specific to the service that interacts with search indices generically. |
|
search/mock
Package mocksearch provides an interface-compatible search index mock
|
Package mocksearch provides an interface-compatible search index mock |
|
server/http
Package server provides an HTTP server comprised of multiple HTTP services
|
Package server provides an HTTP server comprised of multiple HTTP services |
|
server/http/build
Package build contains a builder func for the HTTP server generated by dependency injection tools.
|
Package build contains a builder func for the HTTP server generated by dependency injection tools. |
|
services/accountinvitations
Package accountinvitations provides a series of HTTP handlers for managing webhooks in a compatible database.
|
Package accountinvitations provides a series of HTTP handlers for managing webhooks in a compatible database. |
|
services/accounts
Package accounts provides a series of HTTP handlers for managing accounts in a compatible database.
|
Package accounts provides a series of HTTP handlers for managing accounts in a compatible database. |
|
services/admin
Package admin implements server administrator functions
|
Package admin implements server administrator functions |
|
services/auditlogentries
Package auditlogentries provides a series of HTTP handlers for managing audit log entries in a compatible database.
|
Package auditlogentries provides a series of HTTP handlers for managing audit log entries in a compatible database. |
|
services/authentication
Package authentication implements a user passwords layer for a web server, issuing cookies, validating requests via middleware
|
Package authentication implements a user passwords layer for a web server, issuing cookies, validating requests via middleware |
|
services/capitalism
Package capitalism provides a series of HTTP handlers for managing valid instruments in a compatible database.
|
Package capitalism provides a series of HTTP handlers for managing valid instruments in a compatible database. |
|
services/oauth2clients
Package oauth2clients provides a series of HTTP handlers for managing service OAuth2 clients.
|
Package oauth2clients provides a series of HTTP handlers for managing service OAuth2 clients. |
|
services/servicesettingconfigurations
Package servicesettingconfigurations provides a series of HTTP handlers for managing service setting configurations in a compatible database.
|
Package servicesettingconfigurations provides a series of HTTP handlers for managing service setting configurations in a compatible database. |
|
services/servicesettings
Package servicesettings provides a series of HTTP handlers for managing service settings in a compatible database.
|
Package servicesettings provides a series of HTTP handlers for managing service settings in a compatible database. |
|
services/usernotifications
Package usernotifications provides a series of HTTP handlers for managing user notifications in a compatible database.
|
Package usernotifications provides a series of HTTP handlers for managing user notifications in a compatible database. |
|
services/users
Package users provides a series of HTTP handlers for managing users, passwords, and two factor secrets in a compatible database.
|
Package users provides a series of HTTP handlers for managing users, passwords, and two factor secrets in a compatible database. |
|
services/webhooks
Package webhooks provides a series of HTTP handlers for managing webhooks in a compatible database.
|
Package webhooks provides a series of HTTP handlers for managing webhooks in a compatible database. |
|
uploads/images
Package images is largely (and respectfully) inspired by/copied from this repo: github.com/olahol/go-imageupload
|
Package images is largely (and respectfully) inspired by/copied from this repo: github.com/olahol/go-imageupload |
|
pkg
|
|
|
apiclient
Package apiclient provides an HTTP client that can communicate with and interpret the responses of an instance of the service.
|
Package apiclient provides an HTTP client that can communicate with and interpret the responses of an instance of the service. |
|
types
Package types provides the core data types for the service
|
Package types provides the core data types for the service |
|
types/fakes
Package fakes provides fakes model builders
|
Package fakes provides fakes model builders |
|
types/mock
Package mocktypes provides mockable implementations of every interface defined in the outer types package
|
Package mocktypes provides mockable implementations of every interface defined in the outer types package |
|
tests
|
|
|
integration
Package integration is a series of tests which utilize our HTTP client to talk to a running HTTP server to validate behaviors, inputs, and outputs.
|
Package integration is a series of tests which utilize our HTTP client to talk to a running HTTP server to validate behaviors, inputs, and outputs. |
|
utils
Package testutils contains common functions for integration/load tests
|
Package testutils contains common functions for integration/load tests |
Click to show internal directories.
Click to hide internal directories.