feat(restheadspec): ✨ Add custom SQL JOIN support

- Introduced `x-custom-sql-join` header for custom SQL JOIN clauses.
- Supports single and multiple JOINs, separated by `|`.
- Enhanced query handling to apply custom JOINs directly.
- Updated documentation to reflect new functionality.
- Added tests for parsing custom SQL JOINs from query parameters and headers.

pkg/restheadspec/handler.go

@@ -502,6 +502,15 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		}
 	}
 
+	// Apply custom SQL JOIN clauses
+	if len(options.CustomSQLJoin) > 0 {
+		for _, joinClause := range options.CustomSQLJoin {
+			logger.Debug("Applying custom SQL JOIN: %s", joinClause)
+			// Joins are already sanitized during parsing, so we can apply them directly
+			query = query.Join(joinClause)
+		}
+	}
+
 	// If ID is provided, filter by ID
 	if id != "" {
 		pkName := reflection.GetPrimaryKeyName(model)
@@ -552,6 +561,7 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 				options.Sort,
 				options.CustomSQLWhere,
 				options.CustomSQLOr,
+				options.CustomSQLJoin,
 				expandOpts,
 				options.Distinct,
 				options.CursorForward,