controller

package
v0.0.0-...-d283dcf Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package controller contains framework-owned HTTP handlers for registered routes.

Application code should register routes through package router or generated code. Keeping controller internal prevents external projects from depending on handler factories or mutating controller-owned audit state directly.

Index

Constants

View Source 
const (
	MAX_AVATAR_SIZE = 1024 * 1024 * 2   //nolint:staticcheck // 2M
	MAX_IMPORT_SIZE = 5 * 1024 * 1024   //nolint:staticcheck // 5M
	MAX_UPLOAD_SIZE = 1024 * 1024 * 100 //nolint:staticcheck // 100M
)
View Source 
const (
	TOKEN         = "token"
	ACCESS_TOKEN  = "access_token"  //nolint:staticcheck
	REFRESH_TOKEN = "refresh_token" //nolint:staticcheck
	NAME          = "name"          //nolint:staticcheck
	ID            = "id"
	SESSION_ID    = "session_id" //nolint:staticcheck
)

Variables

View Source 
var Probe = new(probe)

Functions

func Clean 

func Clean()

Clean flushes buffered operation logs during shutdown.

func Create 

func Create[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Create handles a create request with the default factory settings.

func CreateFactory 

func CreateFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

CreateFactory returns a Gin handler that creates one resource.

When M, REQ, and RSP are the same type, the handler binds the JSON body into M, fills the creator/updater fields, runs the create hooks, writes the model through the configured database handler, records an operation log, and returns the created model. Creating a resource requires a body: an absent one is refused, and a client wanting a resource with all defaults states that intent with an explicit {} body.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Create method. Multipart form requests are left unbound so the service can read the request directly.

func CreateMany 

func CreateMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

CreateMany handles a batch create request with the default factory settings.

func CreateManyFactory 

func CreateManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

CreateManyFactory returns a Gin handler that creates multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], fills creator/updater fields on each item, runs batch create hooks, writes the items through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's CreateMany method.

func Delete 

func Delete[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Delete handles a delete request with the default factory settings.

func DeleteFactory 

func DeleteFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

DeleteFactory returns a Gin handler that deletes one resource.

When M, REQ, and RSP are the same type, the handler reads the resource id from the configured route parameter (batch deletion uses the DeleteMany action instead), runs delete hooks, deletes the model through the configured database handler, records an operation log, and returns a success response.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Delete method.

func DeleteMany 

func DeleteMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

DeleteMany handles a batch delete request with the default factory settings.

func DeleteManyFactory 

func DeleteManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

DeleteManyFactory returns a Gin handler that deletes multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], converts ids into model instances, runs batch delete hooks, deletes the models through the configured database handler, records an operation log, and returns a success response.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's DeleteMany method.

func Export 

func Export[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Export handles an export request with the default factory settings.

func ExportFactory 

func ExportFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ExportFactory returns a Gin handler that exports resources.

The handler decodes query parameters into M, applies service filters, runs list hooks, queries the configured database handler with export-oriented limit and query options, delegates byte generation to the phase service's Export method, and writes the result as an attachment

func Get 

func Get[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Get handles a single-resource get request with the default factory settings.

func GetFactory 

func GetFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

GetFactory returns a Gin handler that retrieves one resource.

When M, REQ, and RSP are the same type, the handler reads the configured route parameter as the resource id, applies the expansion and depth query options, runs get hooks, loads the model through the configured database handler, records an operation log, and returns the model.

When REQ or RSP differs from M, the handler delegates the operation to the phase service's Get method with a zero-value REQ. Get handles an HTTP GET request whose body carries no semantics, so nothing is bound into REQ; custom services read parameters from ServiceContext.Query() and ServiceContext.Param().

func Import 

func Import[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Import handles an import request with the default factory settings.

func ImportFactory 

func ImportFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ImportFactory returns a Gin handler that imports resources from an uploaded file.

The handler reads the multipart form file named "file", rejects files larger than MAX_IMPORT_SIZE, passes the file content to the phase service's Import method, and fills creator/updater fields on the returned models. Rows are then written by explicit intent instead of an upsert: a row carrying an ID replaces that existing record (missing IDs fail with 404), and a row without an ID is created (unique-key collisions fail with 409). Both writes share one transaction, so an import is all-or-nothing.

func Init 

func Init() (err error)

Init initializes controller-owned audit logging state.

Init is idempotent after a successful initialization. Failed initialization is not cached, so a later call can retry after configuration has been fixed.

func List 

func List[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

List handles a list request with the default factory settings.

func ListFactory 

func ListFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ListFactory returns a Gin handler that lists resources.

When M, REQ, and RSP are the same type, the handler decodes query parameters into M, applies service filters, runs list hooks, queries the configured database handler, records an operation log, and returns the items with a total count, which is omitted only when cursor pagination is used.

The automatic listing branch supports model schema fields plus framework query parameters for pagination, cursor pagination, expansion, depth, ordering, and field operator filters.

When REQ or RSP differs from M, the handler delegates the operation to the phase service's List method with a zero-value REQ. List handles an HTTP GET request whose body carries no semantics, so nothing is bound into REQ; custom services read query parameters from ServiceContext.Query().

func Patch 

func Patch[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Patch handles a partial update request with the default factory settings.

func PatchFactory 

func PatchFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

PatchFactory returns a Gin handler that partially updates one resource.

When M, REQ, and RSP are the same type, the handler reads the resource id from the configured route parameter (the id carried by the body is ignored), loads the existing record, copies fields present in the request body into that record, sets the updater field, runs patch hooks, writes the patched model through the configured database handler, and records an operation log.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Patch method.

func PatchMany 

func PatchMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

PatchMany handles a batch patch request with the default factory settings.

func PatchManyFactory 

func PatchManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

PatchManyFactory returns a Gin handler that partially updates multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], loads matching existing records for the requested items, copies fields present in each item into those records, runs batch patch hooks, updates the patched models through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's PatchMany method.

func Redoc 

func Redoc(c *gin.Context)

func SSE 

func SSE[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

SSE handles a Server-Sent Events request with the default factory settings.

func SSEFactory 

func SSEFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

SSEFactory returns a Gin handler that streams Server-Sent Events.

The action always delegates to the phase service's SSE method, which opens the stream through ServiceContext.SSE and blocks until it is over; there is no default streaming behavior. The handler distinguishes the two failure shapes by whether the response was written: a setup failure before the stream opened is answered as a regular error envelope, while an error after streaming began can only be logged, because the response is already on the wire.

func Scalar 

func Scalar(c *gin.Context)

func Stoplight 

func Stoplight(c *gin.Context)

func Update 

func Update[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Update handles a full update (replace) request with the default factory settings.

func UpdateFactory 

func UpdateFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

UpdateFactory returns a Gin handler that replaces one resource.

When M, REQ, and RSP are the same type, the handler binds the JSON body into M, reads the resource id from the configured route parameter (the id carried by the body is ignored), sets the updater field, runs update hooks, writes the replacement through the configured database handler, and records an operation log. Existence is enforced by the database layer instead of a pre-read: a missing or soft-deleted record surfaces as database.ErrRecordNotFound and renders 404, and a unique-key collision renders 409. The UpdateBefore service hook therefore runs before existence is known. After a successful write the handler backfills the creation audit columns (created_at/created_by) from the persisted row, keeping the rest of the response object intact so hook-populated fields survive.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Update method.

func UpdateMany 

func UpdateMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

UpdateMany handles a batch update request with the default factory settings.

func UpdateManyFactory 

func UpdateManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

UpdateManyFactory returns a Gin handler that replaces multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], runs batch update hooks, updates the items through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's UpdateMany method.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.