Skip to content

Commit eb130dc

Browse files
author
CaffeinatedTech
committed
Add optional callback URL.
1 parent 479029c commit eb130dc

19 files changed

Lines changed: 215 additions & 41 deletions

‎PLAN.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
**Status:** ✅ **COMPLETE** - StaticSend is production-ready with full deployment and backup system
44
**Last Completed:** Automated S3 backup system with Cronivore monitoring integration
55

6+
**Current Task:** Add optional callback URL to forms, redirecting submitters on success. Update schema, models, API, templates, and tests. (Started: 2025-09-27)
7+
**Last Task:** N/A (new enhancement)
8+
69
## Stage 1: Core Foundation
710
- [x] Initialize Go module structure
811
- [x] Set up basic HTTP server with chi router

‎README.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ A self-hosted, secure contact form processing service for static websites. Enabl
1212
- **🛡️ Authentication Bot Protection** - Optional Turnstile protection for login/register pages
1313
- **⏱️ Rate Limiting** - IP-based request limiting to prevent abuse
1414
- **📧 Email Forwarding** - Send form submissions directly to your inbox
15+
- **↪️ Optional Callback Redirect** - Redirect users to a custom URL after successful submission
1516
- **🖥️ Web Management UI** - HTMX-based interface for easy form management
1617
- **🐳 Docker Ready** - Easy deployment with containerization
1718
- **💾 SQLite Database** - Simple, file-based persistence
@@ -137,6 +138,7 @@ export TURNSTILE_SECRET_KEY=your-turnstile-secret-key
137138
- Form name and domain
138139
- Cloudflare Turnstile keys (public and secret)
139140
- Destination email address
141+
- Optional Callback URL (redirect users here after a successful submission)
140142

141143
### 2. Integrate with Your Static Site
142144

@@ -165,6 +167,8 @@ Form submissions will be:
165167
3. Forwarded to your specified email address
166168
4. Stored in the database for review
167169

170+
If you configured a Callback URL on the form, the submitter will be redirected to that URL with an HTTP 303 See Other after a successful submission. If no Callback URL is configured, the API responds with a JSON payload indicating success (HTTP 201 Created).
171+
168172
## 🔌 API Reference
169173

170174
### Public Endpoints
@@ -177,14 +181,28 @@ Content-Type: application/x-www-form-urlencoded
177181
name=John&email=john@example.com&message=Hello&cf-turnstile-response=token
178182
```
179183

184+
Response:
185+
186+
- 201 Created with JSON body when no Callback URL is configured on the form:
187+
188+
```json
189+
{
190+
"success": true,
191+
"message": "Form submitted successfully",
192+
"submission_id": 123
193+
}
194+
```
195+
196+
- 303 See Other redirect to the configured Callback URL when present.
197+
180198
### Management Endpoints (Require Authentication)
181199

182200
- `POST /api/auth/register` - User registration
183201
- `POST /api/auth/login` - User login
184202
- `GET /api/forms` - List all forms
185-
- `POST /api/forms` - Create new form
203+
- `POST /api/forms` - Create new form (fields: `name`, `domain`, `turnstile_secret`, `forward_email`, `callback_url` [optional])
186204
- `GET /api/forms/{id}` - Get form details
187-
- `PUT /api/forms/{id}` - Update form
205+
- `PUT /api/forms/{id}` - Update form (fields: `name`, `domain`, `turnstile_secret`, `forward_email`, `callback_url` [optional])
188206
- `DELETE /api/forms/{id}` - Delete form
189207
- `GET /api/submissions` - List submissions (with optional form_id filter)
190208

‎integration_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ func SetupIntegrationTest(t *testing.T) *IntegrationTestSuite {
135135
}
136136

137137
// Create test form
138-
testForm, err := models.CreateForm(database.DB, testUser.ID, "Test Form", "example.com", "test-public", "test-secret", "admin@example.com")
138+
testForm, err := models.CreateForm(database.DB, testUser.ID, "Test Form", "example.com", "test-secret", "admin@example.com", "https://example.com/callback", "formkey-int-001")
139139
if err != nil {
140140
t.Fatalf("Failed to create test form: %v", err)
141141
}
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
-- Remove callback_url from forms (requires table rebuild in SQLite)
2+
BEGIN TRANSACTION;
3+
4+
CREATE TABLE forms_new (
5+
id INTEGER PRIMARY KEY AUTOINCREMENT,
6+
user_id INTEGER NOT NULL,
7+
name TEXT NOT NULL,
8+
domain TEXT NOT NULL,
9+
turnstile_secret TEXT NOT NULL,
10+
forward_email TEXT NOT NULL,
11+
form_key TEXT NOT NULL,
12+
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
13+
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
14+
FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE,
15+
UNIQUE(user_id, name),
16+
UNIQUE(form_key)
17+
);
18+
19+
INSERT INTO forms_new (id, user_id, name, domain, turnstile_secret, forward_email, form_key, created_at, updated_at)
20+
SELECT id, user_id, name, domain, turnstile_secret, forward_email, form_key, created_at, updated_at
21+
FROM forms;
22+
23+
DROP TABLE forms;
24+
ALTER TABLE forms_new RENAME TO forms;
25+
26+
CREATE INDEX idx_forms_user_id ON forms(user_id);
27+
CREATE INDEX idx_forms_form_key ON forms(form_key);
28+
29+
COMMIT;
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
-- Add optional callback_url to forms
2+
ALTER TABLE forms ADD COLUMN callback_url TEXT;

‎pkg/api/forms.go‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,21 @@ func (h *FormHandler) CreateForm(w http.ResponseWriter, r *http.Request) {
4141
domain := r.FormValue("domain")
4242
turnstileSecret := r.FormValue("turnstile_secret")
4343
forwardEmail := r.FormValue("forward_email")
44+
callbackURL := r.FormValue("callback_url")
4445

4546
if name == "" || domain == "" || turnstileSecret == "" || forwardEmail == "" {
4647
http.Error(w, "Name, domain, secret key, and forward email are required", http.StatusBadRequest)
4748
return
4849
}
4950

51+
// Validate callback URL if provided
52+
if callbackURL != "" {
53+
if !utils.IsValidCallbackURL(callbackURL) {
54+
http.Error(w, "Invalid callback URL. Must be http(s)://...", http.StatusBadRequest)
55+
return
56+
}
57+
}
58+
5059
// Auto-generate unique form key
5160
formKey, err := utils.GenerateFormKey()
5261
if err != nil {
@@ -65,7 +74,7 @@ func (h *FormHandler) CreateForm(w http.ResponseWriter, r *http.Request) {
6574
return
6675
}
6776

68-
_, err = models.CreateForm(h.DB, user.ID, name, domain, turnstileSecret, forwardEmail, formKey)
77+
_, err = models.CreateForm(h.DB, user.ID, name, domain, turnstileSecret, forwardEmail, callbackURL, formKey)
6978
if err != nil {
7079
http.Error(w, "Failed to create form", http.StatusInternalServerError)
7180
return
@@ -202,14 +211,23 @@ func (h *FormHandler) UpdateForm(w http.ResponseWriter, r *http.Request) {
202211
domain := r.FormValue("domain")
203212
turnstileSecret := r.FormValue("turnstile_secret")
204213
forwardEmail := r.FormValue("forward_email")
214+
callbackURL := r.FormValue("callback_url")
205215

206216
if name == "" || domain == "" || turnstileSecret == "" || forwardEmail == "" {
207217
http.Error(w, "Name, domain, secret key, and forward email are required", http.StatusBadRequest)
208218
return
209219
}
210220

221+
// Validate callback URL if provided
222+
if callbackURL != "" {
223+
if !utils.IsValidCallbackURL(callbackURL) {
224+
http.Error(w, "Invalid callback URL. Must be http(s)://...", http.StatusBadRequest)
225+
return
226+
}
227+
}
228+
211229
// Update form
212-
err = models.UpdateForm(h.DB, formID, name, domain, turnstileSecret, forwardEmail)
230+
err = models.UpdateForm(h.DB, formID, name, domain, turnstileSecret, forwardEmail, callbackURL)
213231
if err != nil {
214232
http.Error(w, "Failed to update form", http.StatusInternalServerError)
215233
return

‎pkg/api/submission.go‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -115,14 +115,20 @@ func (h *SubmissionHandler) SubmitForm(w http.ResponseWriter, r *http.Request) {
115115
}
116116
}()
117117

118-
// Return success response
119-
w.Header().Set("Content-Type", "application/json")
120-
w.WriteHeader(http.StatusCreated)
121-
json.NewEncoder(w).Encode(map[string]interface{}{
122-
"success": true,
123-
"message": "Form submitted successfully",
124-
"submission_id": submission.ID,
125-
})
118+
// If a callback URL is configured for this form, redirect the end-user
119+
if form.CallbackURL != "" {
120+
http.Redirect(w, r, form.CallbackURL, http.StatusSeeOther)
121+
return
122+
}
123+
124+
// Otherwise return success JSON response
125+
w.Header().Set("Content-Type", "application/json")
126+
w.WriteHeader(http.StatusCreated)
127+
json.NewEncoder(w).Encode(map[string]interface{}{
128+
"success": true,
129+
"message": "Form submitted successfully",
130+
"submission_id": submission.ID,
131+
})
126132
}
127133

128134
// getClientIP extracts the client IP address from the request

‎pkg/database/database.go‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,24 @@ func runMigrations() error {
126126
return fmt.Errorf("failed to check for forms table columns: %w", err)
127127
}
128128

129+
// Ensure callback_url column exists (005 migration)
130+
var callbackColumn string
131+
err = DB.QueryRow("SELECT name FROM pragma_table_info('forms') WHERE name = 'callback_url'").Scan(&callbackColumn)
132+
if err == sql.ErrNoRows {
133+
log.Println("Running callback_url column migration...")
134+
migrationSQL, err := os.ReadFile("migrations/005_add_callback_url.up.sql")
135+
if err != nil {
136+
return fmt.Errorf("failed to read migration file: %w", err)
137+
}
138+
139+
if _, err := DB.Exec(string(migrationSQL)); err != nil {
140+
return fmt.Errorf("failed to execute migration: %w", err)
141+
}
142+
log.Println("callback_url column migration completed successfully")
143+
} else if err != nil && err != sql.ErrNoRows {
144+
return fmt.Errorf("failed to check for callback_url column: %w", err)
145+
}
146+
129147
return nil
130148
}
131149

‎pkg/models/form.go‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,18 @@ type Form struct {
1313
Domain string `json:"domain"`
1414
TurnstileSecret string `json:"turnstile_secret"` // Private key for validation
1515
ForwardEmail string `json:"forward_email"`
16+
CallbackURL string `json:"callback_url,omitempty"`
1617
FormKey string `json:"form_key"` // Generated unique key
1718
SubmissionCount int `json:"submission_count"`
1819
CreatedAt time.Time `json:"created_at"`
1920
UpdatedAt time.Time `json:"updated_at"`
2021
}
2122

2223
// CreateForm creates a new form in the database
23-
func CreateForm(db *sql.DB, userID int64, name, domain, turnstileSecret, forwardEmail, formKey string) (*Form, error) {
24+
func CreateForm(db *sql.DB, userID int64, name, domain, turnstileSecret, forwardEmail, callbackURL, formKey string) (*Form, error) {
2425
result, err := db.Exec(
25-
"INSERT INTO forms (user_id, name, domain, turnstile_secret, forward_email, form_key) VALUES (?, ?, ?, ?, ?, ?)",
26-
userID, name, domain, turnstileSecret, forwardEmail, formKey,
26+
"INSERT INTO forms (user_id, name, domain, turnstile_secret, forward_email, callback_url, form_key) VALUES (?, ?, ?, ?, ?, ?, ?)",
27+
userID, name, domain, turnstileSecret, forwardEmail, callbackURL, formKey,
2728
)
2829
if err != nil {
2930
return nil, err
@@ -41,9 +42,9 @@ func CreateForm(db *sql.DB, userID int64, name, domain, turnstileSecret, forward
4142
func GetFormByID(db *sql.DB, id int64) (*Form, error) {
4243
var form Form
4344
err := db.QueryRow(
44-
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, form_key, created_at, updated_at FROM forms WHERE id = ?",
45+
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, COALESCE(callback_url, ''), form_key, created_at, updated_at FROM forms WHERE id = ?",
4546
id,
46-
).Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.FormKey, &form.CreatedAt, &form.UpdatedAt)
47+
).Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.CallbackURL, &form.FormKey, &form.CreatedAt, &form.UpdatedAt)
4748

4849
if err != nil {
4950
if err == sql.ErrNoRows {
@@ -58,7 +59,7 @@ func GetFormByID(db *sql.DB, id int64) (*Form, error) {
5859
// GetFormsByUserID retrieves all forms for a specific user
5960
func GetFormsByUserID(db *sql.DB, userID int64) ([]Form, error) {
6061
rows, err := db.Query(
61-
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, form_key, created_at, updated_at FROM forms WHERE user_id = ? ORDER BY created_at DESC",
62+
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, COALESCE(callback_url, ''), form_key, created_at, updated_at FROM forms WHERE user_id = ? ORDER BY created_at DESC",
6263
userID,
6364
)
6465
if err != nil {
@@ -69,7 +70,7 @@ func GetFormsByUserID(db *sql.DB, userID int64) ([]Form, error) {
6970
var forms []Form
7071
for rows.Next() {
7172
var form Form
72-
if err := rows.Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.FormKey, &form.CreatedAt, &form.UpdatedAt); err != nil {
73+
if err := rows.Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.CallbackURL, &form.FormKey, &form.CreatedAt, &form.UpdatedAt); err != nil {
7374
return nil, err
7475
}
7576
forms = append(forms, form)
@@ -93,9 +94,9 @@ func FormExists(db *sql.DB, userID int64, name string) (bool, error) {
9394
func GetFormByKey(db *sql.DB, formKey string) (*Form, error) {
9495
var form Form
9596
err := db.QueryRow(
96-
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, form_key, created_at, updated_at FROM forms WHERE form_key = ?",
97+
"SELECT id, user_id, name, domain, turnstile_secret, forward_email, COALESCE(callback_url, ''), form_key, created_at, updated_at FROM forms WHERE form_key = ?",
9798
formKey,
98-
).Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.FormKey, &form.CreatedAt, &form.UpdatedAt)
99+
).Scan(&form.ID, &form.UserID, &form.Name, &form.Domain, &form.TurnstileSecret, &form.ForwardEmail, &form.CallbackURL, &form.FormKey, &form.CreatedAt, &form.UpdatedAt)
99100

100101
if err != nil {
101102
if err == sql.ErrNoRows {
@@ -108,10 +109,10 @@ func GetFormByKey(db *sql.DB, formKey string) (*Form, error) {
108109
}
109110

110111
// UpdateForm updates a form in the database
111-
func UpdateForm(db *sql.DB, formID int64, name, domain, turnstileSecret, forwardEmail string) error {
112+
func UpdateForm(db *sql.DB, formID int64, name, domain, turnstileSecret, forwardEmail, callbackURL string) error {
112113
_, err := db.Exec(
113-
"UPDATE forms SET name = ?, domain = ?, turnstile_secret = ?, forward_email = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
114-
name, domain, turnstileSecret, forwardEmail, formID,
114+
"UPDATE forms SET name = ?, domain = ?, turnstile_secret = ?, forward_email = ?, callback_url = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
115+
name, domain, turnstileSecret, forwardEmail, callbackURL, formID,
115116
)
116117
return err
117118
}

‎pkg/models/form_test.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ func TestCreateForm(t *testing.T) {
3535
}
3636

3737
// Test duplicate form name for same user
38-
_, err = CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "manual_form_key_123")
38+
_, err = CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "", "manual_form_key_123")
3939
if err == nil {
4040
t.Error("Expected error when creating form with duplicate name for same user")
4141
}
@@ -66,7 +66,7 @@ func TestGetFormByID(t *testing.T) {
6666
t.Fatalf("Failed to create user: %v", err)
6767
}
6868

69-
createdForm, err := CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "form_key_789")
69+
createdForm, err := CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "", "form_key_789")
7070
if err != nil {
7171
t.Fatalf("Failed to create form: %v", err)
7272
}
@@ -159,7 +159,7 @@ func TestFormExists(t *testing.T) {
159159
t.Fatalf("Failed to create user: %v", err)
160160
}
161161

162-
_, err = CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "form_key_789")
162+
_, err = CreateForm(db, user.ID, "contact", "example.com", "turnstile_secret_456", "admin@example.com", "", "form_key_789")
163163
if err != nil {
164164
t.Fatalf("Failed to create form: %v", err)
165165
}

0 commit comments

Comments
 (0)