Add DBTransaction interface documentation for ORM support
Updated JWT documentation to reflect the new DBTransaction interface that allows ORM transactions to be used directly with the JWT package. Changes: - Added explanation of DBTransaction interface - Documented that *sql.Tx automatically implements the interface - Added examples showing GORM transaction usage (tx.Statement.ConnPool) - Added examples showing Bun transaction usage (bunDB.BeginTx) - Updated validation and revocation sections with ORM examples - Clarified that users can choose between ORM or standard transactions Benefits: - GORM users can use gormDB.Begin() and pass tx.Statement.ConnPool - Bun users can use bunDB.BeginTx() and pass tx directly - Standard library users continue using db.Begin() as before - No need to extract/manage separate transactions for different libraries 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
65
JWT.md
65
JWT.md
@@ -159,7 +159,9 @@ token, expiry, err := gen.NewRefresh(42, true)
|
||||
|
||||
## Token Validation
|
||||
|
||||
Tokens must be validated within a transaction context:
|
||||
Tokens must be validated within a transaction context. The package accepts any transaction type that implements the `DBTransaction` interface (which `*sql.Tx` does automatically):
|
||||
|
||||
### Using Standard Library
|
||||
|
||||
```go
|
||||
// Begin transaction
|
||||
@@ -185,6 +187,22 @@ if err != nil {
|
||||
tx.Commit()
|
||||
```
|
||||
|
||||
### Using ORM Transactions
|
||||
|
||||
You can use ORM transactions directly since they implement the `DBTransaction` interface:
|
||||
|
||||
```go
|
||||
// GORM transaction
|
||||
tx := gormDB.Begin()
|
||||
token, err := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
|
||||
tx.Commit()
|
||||
|
||||
// Bun transaction
|
||||
tx, _ := bunDB.BeginTx(context.Background(), nil)
|
||||
token, err := gen.ValidateAccess(tx, tokenString)
|
||||
tx.Commit()
|
||||
```
|
||||
|
||||
### Token Properties
|
||||
|
||||
After validation, you can access token claims:
|
||||
@@ -204,9 +222,12 @@ ttl := token.TTL // "session" or "exp"
|
||||
|
||||
## Token Revocation
|
||||
|
||||
The revocation methods accept any transaction implementing the `DBTransaction` interface.
|
||||
|
||||
### Revoking a Token
|
||||
|
||||
```go
|
||||
// Using standard library
|
||||
tx, _ := db.Begin()
|
||||
defer tx.Rollback()
|
||||
|
||||
@@ -222,6 +243,12 @@ if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
tx.Commit()
|
||||
|
||||
// Or using GORM
|
||||
tx := gormDB.Begin()
|
||||
token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
|
||||
token.Revoke(tx.Statement.ConnPool)
|
||||
tx.Commit()
|
||||
```
|
||||
|
||||
@@ -358,6 +385,8 @@ CREATE INDEX IF NOT EXISTS idx_jwtblacklist_sub ON jwtblacklist(sub);
|
||||
|
||||
### GORM
|
||||
|
||||
GORM transactions can be used directly with the JWT package:
|
||||
|
||||
```go
|
||||
import (
|
||||
"gorm.io/gorm"
|
||||
@@ -383,19 +412,25 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
|
||||
TableConfig: jwt.DefaultTableConfig(),
|
||||
})
|
||||
|
||||
// Use with transactions
|
||||
tx, _ := sqlDB.Begin()
|
||||
defer tx.Rollback()
|
||||
|
||||
token, _ := gen.ValidateAccess(tx, tokenString)
|
||||
|
||||
// Option 1: Use GORM transactions directly
|
||||
tx := gormDB.Begin()
|
||||
token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
|
||||
tx.Commit()
|
||||
|
||||
// Option 2: Use standard sql.DB transactions
|
||||
sqlTx, _ := sqlDB.Begin()
|
||||
defer sqlTx.Rollback()
|
||||
token, _ := gen.ValidateAccess(sqlTx, tokenString)
|
||||
sqlTx.Commit()
|
||||
```
|
||||
|
||||
### Bun
|
||||
|
||||
Bun transactions can be used directly with the JWT package:
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"github.com/uptrace/bun"
|
||||
"github.com/uptrace/bun/dialect/pgdialect"
|
||||
@@ -423,13 +458,17 @@ gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
|
||||
TableConfig: jwt.DefaultTableConfig(),
|
||||
})
|
||||
|
||||
// Use with transactions
|
||||
tx, _ := sqlDB.Begin()
|
||||
defer tx.Rollback()
|
||||
|
||||
token, _ := gen.ValidateAccess(tx, tokenString)
|
||||
|
||||
// Option 1: Use Bun transactions directly (recommended)
|
||||
ctx := context.Background()
|
||||
tx, _ := bunDB.BeginTx(ctx, nil)
|
||||
token, _ := gen.ValidateAccess(tx, tokenString) // Bun's tx implements DBTransaction
|
||||
tx.Commit()
|
||||
|
||||
// Option 2: Use standard sql.DB transactions
|
||||
sqlTx, _ := sqlDB.Begin()
|
||||
defer sqlTx.Rollback()
|
||||
token, _ := gen.ValidateAccess(sqlTx, tokenString)
|
||||
sqlTx.Commit()
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Reference in New Issue
Block a user