This controller provides the public API for managing Cloudflare Tunnels + * and their ingress mappings. All endpoints require authentication via OIDC + * and are protected by role-based access control.
+ * + *Base URL: {@code /cloudflare}
+ * + *Authentication: OIDC-based with role-based access
+ * + *Available Roles:
+ *Example Usage:
+ *
+ * # Get all tunnels (requires USER role)
+ * curl -H "Authorization: Bearer <token>" \
+ * https://api.example.com/cloudflare/tunnels
+ *
+ * # Add a mapping (requires ADMIN role)
+ * curl -X POST -H "Authorization: Bearer <token>" \
+ * -H "Content-Type: application/json" \
+ * -d '{"hostname":"api.example.com","service":"http://localhost:8080"}' \
+ * https://api.example.com/cloudflare/tunnels/{tunnelId}/mappings
+ *
+ *
+ * @see CloudflareAPIService
+ * @see MappingRequestService
+ */
@RestController
@RequestMapping("/cloudflare")
public class TunnelController implements ErrorController {
@@ -63,9 +97,23 @@ public class TunnelController implements ErrorController {
@Autowired
private UserRepository userRepository;
+ /**
+ * Current environment (loaded from spring.profiles.active).
+ */
@Value("${spring.profiles.active}")
private String environment;
+ /**
+ * Get current user information.
+ *
+ * Returns the authenticated user's username and roles.
+ * + * @param oidcUser The authenticated OIDC user + * @return Map containing username and roles + * + * @security Requires USER role + * @response 200 OK + */ @PreAuthorize("hasAnyRole('USER')") @GetMapping("/whoami") public MapFetches the complete list of tunnels from Cloudflare, + * including their status and configuration from the Cloudflare API.
+ * + * @return Map containing list of all tunnels + * + * @security Requires USER role + * @response 200 OK with tunnel list + * @response 500 Internal Server Error if API call fails + * @see Cloudflare API + */ @PreAuthorize("hasAnyRole('USER')") @GetMapping("/tunnels") @Operation( security = { @SecurityRequirement(name = "oidcAuth") } ) @@ -92,6 +153,19 @@ public class TunnelController implements ErrorController { return ResponseEntity.ok(jsonResponse); } + /** + * Get locally configured tunnels. + * + *Returns the tunnels that have been configured locally + * with environment associations.
+ * + * @return Map containing list of configured tunnels + * + * @security Requires USER role + * @response 200 OK with tunnel list + * @response 500 Internal Server Error if database access fails + * @see CloudflareAPIService#getAllConfiguredTunnels() + */ @PreAuthorize("hasAnyRole('USER')") @GetMapping("/configured/tunnels") public ResponseEntityReturns all pending, approved, and rejected mapping requests.
+ * + * @return Map containing list of all requests + * + * @security Requires USER role + * @response 200 OK with request list + * @response 500 Internal Server Error if database access fails + */ @PreAuthorize("hasAnyRole('USER')") @GetMapping("/requests") public ResponseEntityFetches the complete configuration for a specific tunnel, + * including all ingress rules.
+ * + * @param tunnelId The Cloudflare tunnel ID (UUID) + * @return Map containing tunnel configuration + * + * @security Requires DEVELOPER role + * @response 200 OK with configuration + * @response 500 Internal Server Error + * @see Cloudflare API + */ @PreAuthorize("hasAnyRole('DEVELOPER')") @GetMapping("/tunnels/{tunnelId}/mappings") public ResponseEntityAdds a new ingress rule to the tunnel configuration. + * The new rule is inserted at the second-to-last position, + * before any catch-all rule.
+ * + * @param tunnelId The Cloudflare tunnel ID (UUID) + * @param ingress The ingress rule to add + * @return Map containing the updated configuration + * + * @security Requires ADMIN role + * @response 200 OK with updated configuration + * @response 400 Bad Request if ingress is invalid + * @response 500 Internal Server Error + * + * @example + * { + * "hostname": "api.example.com", + * "service": "http://localhost:8080", + * "originRequest": {"noTLSVerify": true} + * } + */ @PreAuthorize("hasAnyRole('ADMIN')") @PostMapping("/tunnels/{tunnelId}/mappings") public ResponseEntityRemoves an ingress rule by hostname from the tunnel configuration.
+ * + * @param tunnelId The Cloudflare tunnel ID (UUID) + * @param ingress Ingress containing hostname to delete (only hostname field is used) + * @return Map containing the result + * + * @security Requires DEVELOPER role + * @response 200 OK with updated configuration + * @response 409 Conflict if hostname not found + */ @PreAuthorize("hasAnyRole('DEVELOPER')") @DeleteMapping("/tunnels/{tunnelId}/mappings") public ResponseEntityCreates a new request for changing tunnel ingress mappings. + * The request starts in PENDING status and must be approved + * before the changes are applied.
+ * + * @param tunnelId The Cloudflare tunnel ID (UUID) + * @param oidcUser The authenticated user + * @param ingess The ingress configuration to request + * @return The created request with PENDING status + * + * @security Requires DEVELOPER role + * @response 201 Created with request + * @response 400 Bad Request if invalid + * + * @see MappingRequestService#createMappingRequest(String, Ingress, OidcUser) + */ @PreAuthorize("hasAnyRole('DEVELOPER')") @PostMapping("/tunnels/configure/{tunnelId}/requests") public ResponseEntityApproves a pending mapping request. If approved, the + * mapping will be applied to the Cloudflare tunnel.
+ * + * @param requestId The ID of the request to approve + * @param oidcUser The approver (must have APPROVER role) + * @return The updated request with APPROVED status + * + * @security Requires APPROVER role + * @response 200 OK with approved request + * @response 404 Not Found if request doesn't exist + * @response 409 Conflict if request already processed + */ @PreAuthorize("hasAnyRole('APPROVER')") @PutMapping("/requests/{requestId}/approve") public ResponseEntityRejects a pending mapping request. No changes + * will be made to the tunnel.
+ * + * @param requestId The ID of the request to reject + * @param oidcUser The rejecter (must have APPROVER role) + * @return The updated request with REJECTED status + * + * @security Requires APPROVER role + * @response 200 OK with rejected request + * @response 404 Not Found + * @response 409 Conflict + */ @PreAuthorize("hasAnyRole('APPROVER')") @PutMapping("/requests/{requestId}/reject") public ResponseEntityCreates a local configuration entry for a tunnel, + * associating it with the current environment (from spring.profiles.active).
+ * + *Response Codes:
+ *