README
¶
Momobase
Momobase is an embeddable Go package for accepting, routing, and reconciling payments through provider adapters.
Install
go get github.com/momobasehq/momobase@latest
Start an instance
package main
import (
"log"
"github.com/momobasehq/momobase"
"github.com/momobasehq/momobase/providers/dummy"
)
func main() {
instance, err := momobase.New(
momobase.WithProvider("dummy", dummy.New),
)
if err != nil {
log.Fatal(err)
}
defer instance.Close()
log.Fatal(instance.Run())
}
New reads environment configuration by default. Pass WithConfig for explicit configuration, WithConfigFunc for ordered overrides, WithLogger for a slog.Logger, and WithProvider or WithProviders for adapters. At least one provider is required; the included dummy provider is deterministic and moves no money.
Public interface
New(...Option)constructs the database, HTTP API, provider runtime, workers, and hooks.Serve(ctx)runs until cancellation;Run()adds interrupt and termination signal handling.Close()stops workers and closes owned resources. Call it for every successfulNew.App()exposes the Fiber application for tests, mounting, or extra routes.DB()andLogger()expose the instance-owned GORM database and structured logger.Migrate(ctx)applies schema migrations when your host controls migration timing.SeedAdmin(ctx, email, password, name)creates the first administrator.OnPaymentRequest()andOnTransactionChanged()expose typed lifecycle hooks.
Provider contracts and helpers live in providers, the safe reference adapter lives in providers/dummy, and typed lifecycle events live in hooks.
See the documentation and API reference.
Development
make quality
make coverage
Releases are ordinary semantic-version Go module tags. A release tag publishes the module, GitHub release, and release OpenAPI files.
License
Documentation
¶
Overview ¶
Package momobase embeds the Momobase payment orchestration server in a Go application and extends it with custom payment providers.
New constructs an instance from configuration and the registered providers, and Run or Serve starts its HTTP server and background workers:
instance, err := momobase.New(
momobase.WithProvider("acme_pay", acme.New),
)
if err != nil {
log.Fatal(err)
}
defer instance.Close()
log.Fatal(instance.Run())
Provider contracts and helpers live in the providers package. Register a providers.PaymentProvider factory under a provider code with WithProvider. Accounts for that code are then created, configured, and activated through the Admin API.
Momobase registers no providers on its own: a build carries exactly the providers it asks for, and New reports an error when none are registered. providers/dummy is the included reference adapter and moves no money.
@title Momobase API @version 1.0 @description Embeddable payment orchestration API for application payments and administrative operations. @BasePath / @schemes http https @securityDefinitions.apikey BearerAuth @in header @name Authorization @description Enter a bearer token using the format: Bearer {token}
Index ¶
- type AppConfig
- type Config
- type DatabaseConfig
- type FeaturesConfig
- type Instance
- func (i *Instance) Addr() string
- func (i *Instance) App() *fiber.App
- func (i *Instance) Close() error
- func (i *Instance) DB() *gorm.DB
- func (i *Instance) Logger() *slog.Logger
- func (i *Instance) Migrate(ctx context.Context) error
- func (i *Instance) OnPaymentRequest() *hooks.Hook[hooks.PaymentRequestEvent]
- func (i *Instance) OnTransactionChanged() *hooks.Hook[hooks.TransactionChangedEvent]
- func (i *Instance) Run() error
- func (i *Instance) SeedAdmin(ctx context.Context, email, password, name string) error
- func (i *Instance) Serve(ctx context.Context) error
- type LogConfig
- type Option
- type SecurityConfig
- type WorkersConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
Config contains all application configuration groups.
func LoadConfig ¶
LoadConfig reads configuration from the environment and rejects invalid explicitly configured boolean and duration values. New calls it when no configuration is supplied through WithConfig.
type DatabaseConfig ¶
type DatabaseConfig = bootstrap.DatabaseConfig
DatabaseConfig contains settings shared by the supported database drivers.
type FeaturesConfig ¶
type FeaturesConfig = bootstrap.FeaturesConfig
FeaturesConfig controls optional application behavior.
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
Instance is a configured Momobase server and the runtime dependencies it owns.
func New ¶
New builds an instance from the supplied options, opening the database and preparing the HTTP server, providers, and background workers. Configuration is read from the environment unless WithConfig is supplied. The caller owns the returned instance and must Close it to release its connections.
func (*Instance) Addr ¶
Addr returns the address the HTTP server listens on. A configured port of 0 reads back as the port the kernel chose once Serve has bound the listener.
func (*Instance) App ¶
App returns the Fiber application, which may be mounted in an existing Fiber app, exercised with App().Test, or extended with additional routes instead of calling Serve or Run.
Momobase runs on fasthttp rather than net/http, so this is a *fiber.App and not an http.Handler; an application serving Momobase alongside net/http routes has to adapt at its own boundary.
func (*Instance) Close ¶
Close stops an active server and its workers before closing the database connection pool. It is safe to call Close more than once.
func (*Instance) Migrate ¶
Migrate applies pending schema migrations and converges the schema with the current models. It runs automatically during New unless the AutoMigrate feature is disabled, and is safe to call more than once.
func (*Instance) OnPaymentRequest ¶
func (i *Instance) OnPaymentRequest() *hooks.Hook[hooks.PaymentRequestEvent]
OnPaymentRequest returns the blocking hook invoked for each normalized new payment request before routing and persistence. Idempotent replays skip it.
func (*Instance) OnTransactionChanged ¶
func (i *Instance) OnTransactionChanged() *hooks.Hook[hooks.TransactionChangedEvent]
OnTransactionChanged returns the post-commit hook invoked when a transaction status is persisted from the request, webhook, or reconciliation path.
func (*Instance) Run ¶
Run serves the instance until the process receives an interrupt or termination signal, then shuts it down gracefully.
type Option ¶
type Option func(*options)
Option customizes the instance constructed by New.
func WithConfig ¶
WithConfig uses cfg instead of reading configuration from the environment.
func WithConfigFunc ¶
WithConfigFunc applies fn to the resolved configuration before the instance is built. Functions run in the order supplied, after any WithConfig value.
func WithLogger ¶
WithLogger uses log instead of a logger derived from the configured log level.
func WithProvider ¶
WithProvider registers a payment provider under code, replacing any provider previously registered under the same code. The code is the value operators select when creating a provider account through the Admin API.
Momobase registers no providers of its own, so at least one is required. The reference adapter in providers/dummy is registered the same way as any other:
momobase.New(momobase.WithProvider("acme_pay", acme.New))
type SecurityConfig ¶
type SecurityConfig = bootstrap.SecurityConfig
SecurityConfig contains encryption, token, and application credential settings.
type WorkersConfig ¶
type WorkersConfig = bootstrap.WorkersConfig
WorkersConfig controls background task activation and scheduling.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
customprovider
command
Package main runs a Momobase server extended with a custom payment provider.
|
Package main runs a Momobase server extended with a custom payment provider. |
|
extension
Package extension demonstrates a compiled, app-scoped Momobase extension.
|
Package extension demonstrates a compiled, app-scoped Momobase extension. |
|
Package hooks provides typed extension points for Momobase lifecycle events.
|
Package hooks provides typed extension points for Momobase lifecycle events. |
|
internal
|
|
|
bootstrap
Package bootstrap constructs the application runtime from configuration and manages its database, HTTP server, workers, and lifecycle.
|
Package bootstrap constructs the application runtime from configuration and manages its database, HTTP server, workers, and lifecycle. |
|
domain
Package domain defines the persistent models and shared state constants used throughout Momobase.
|
Package domain defines the persistent models and shared state constants used throughout Momobase. |
|
dto
Package dto holds the request payloads the HTTP API accepts, the rules each one must satisfy, and the normalization applied before those rules are checked.
|
Package dto holds the request payloads the HTTP API accepts, the rules each one must satisfy, and the normalization applied before those rules are checked. |
|
http
Package httpx assembles the application's HTTP routes and middleware stack.
|
Package httpx assembles the application's HTTP routes and middleware stack. |
|
http/admin
Package admin provides HTTP handlers for authenticated administrative APIs.
|
Package admin provides HTTP handlers for authenticated administrative APIs. |
|
http/apidoc
Package apidoc contains schemas used only to describe the HTTP API.
|
Package apidoc contains schemas used only to describe the HTTP API. |
|
http/middleware
Package middleware provides authentication, authorization, logging, and request-safety middleware for the HTTP API.
|
Package middleware provides authentication, authorization, logging, and request-safety middleware for the HTTP API. |
|
http/public
Package public provides HTTP handlers for client-facing payment APIs.
|
Package public provides HTTP handlers for client-facing payment APIs. |
|
http/webhooks
Package webhooks provides HTTP handlers for incoming provider webhooks.
|
Package webhooks provides HTTP handlers for incoming provider webhooks. |
|
migrations
Package migrations applies ordered schema changes that GORM's AutoMigrate cannot express.
|
Package migrations applies ordered schema changes that GORM's AutoMigrate cannot express. |
|
platform
Package platform provides shared HTTP, cryptographic, token, and identifier helpers for the application.
|
Package platform provides shared HTTP, cryptographic, token, and identifier helpers for the application. |
|
repository
Package repository is the only place in Momobase that reaches the database.
|
Package repository is the only place in Momobase that reaches the database. |
|
service/audit
Package audit records security- and administration-relevant actions.
|
Package audit records security- and administration-relevant actions. |
|
service/identity
Package services implements Momobase's application-level business workflows.
|
Package services implements Momobase's application-level business workflows. |
|
service/payment
Package payment turns a validated request into a recorded transaction.
|
Package payment turns a validated request into a recorded transaction. |
|
service/provider
Package provider owns the lifecycle of the payment adapters a deployment runs.
|
Package provider owns the lifecycle of the payment adapters a deployment runs. |
|
service/reconciliation
Package reconciliation settles transactions the request path left unresolved.
|
Package reconciliation settles transactions the request path left unresolved. |
|
service/routing
Package routing decides which provider account executes a payment.
|
Package routing decides which provider account executes a payment. |
|
service/webhook
Package webhook applies provider callbacks to the transactions they describe.
|
Package webhook applies provider callbacks to the transactions they describe. |
|
testsupport
Package testsupport builds a fully wired service stack backed by a throwaway in-memory database, so a test can exercise a real payment path instead of a mock.
|
Package testsupport builds a fully wired service stack backed by a throwaway in-memory database, so a test can exercise a real payment path instead of a mock. |
|
utils
Package utils holds small, dependency-free helpers shared across Momobase's packages, including the provider adapters.
|
Package utils holds small, dependency-free helpers shared across Momobase's packages, including the provider adapters. |
|
workers
Package workers runs named background tasks on configurable intervals and coordinates their shutdown.
|
Package workers runs named background tasks on configurable intervals and coordinates their shutdown. |
|
Package providers defines payment-provider contracts and shared utilities for configuring providers, issuing requests, and normalizing provider responses.
|
Package providers defines payment-provider contracts and shared utilities for configuring providers, issuing requests, and normalizing provider responses. |
|
dummy
Package dummy provides a payment provider that simulates payments entirely in memory.
|
Package dummy provides a payment provider that simulates payments entirely in memory. |