diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/pom.xml b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/pom.xml new file mode 100644 index 0000000000..8c61908952 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/pom.xml @@ -0,0 +1,63 @@ + + + + + + + org.wso2.carbon.identity.server.api + org.wso2.carbon.identity.api.server.debug + 1.5.18-SNAPSHOT + ../pom.xml + + + 4.0.0 + org.wso2.carbon.identity.api.server.debug.common + jar + WSO2 Identity Server - Debug API Common + WSO2 Identity Server - Common classes for Debug API + + + + + org.apache.maven.plugins + maven-compiler-plugin + ${maven.compiler.plugin.version} + + 1.8 + 1.8 + + + + org.apache.maven.plugins + maven-jar-plugin + 3.3.0 + + + + + + + org.wso2.carbon.identity.framework + org.wso2.carbon.identity.debug.framework + 7.10.35 + provided + + + + diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/src/main/java/org/wso2/carbon/identity/api/server/debug/common/DebugServiceHolder.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/src/main/java/org/wso2/carbon/identity/api/server/debug/common/DebugServiceHolder.java new file mode 100644 index 0000000000..4a2fefcb72 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.common/src/main/java/org/wso2/carbon/identity/api/server/debug/common/DebugServiceHolder.java @@ -0,0 +1,49 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.common; + +import org.wso2.carbon.context.PrivilegedCarbonContext; +import org.wso2.carbon.identity.debug.framework.core.DebugRequestCoordinator; + +/** + * Holder class for Debug Framework OSGi services. + */ +public class DebugServiceHolder { + + private DebugServiceHolder() { + + } + + private static class DebugRequestCoordinatorHolder { + + private static final DebugRequestCoordinator INSTANCE = (DebugRequestCoordinator) + PrivilegedCarbonContext.getThreadLocalCarbonContext() + .getOSGiService(DebugRequestCoordinator.class, null); + } + + /** + * Get DebugRequestCoordinator OSGi service. + * + * @return DebugRequestCoordinator + */ + public static DebugRequestCoordinator getDebugRequestCoordinator() { + + return DebugRequestCoordinatorHolder.INSTANCE; + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/pom.xml b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/pom.xml new file mode 100644 index 0000000000..a4e41a01fb --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/pom.xml @@ -0,0 +1,186 @@ + + + + + + + org.wso2.carbon.identity.server.api + org.wso2.carbon.identity.api.server.debug + 1.5.18-SNAPSHOT + ../pom.xml + + + 4.0.0 + org.wso2.carbon.identity.api.server.debug.v1 + jar + WSO2 Identity Server - Debug API + WSO2 Identity Server - Debug API v1.0 + + + ${project.basedir}/../../../findbugs-exclude-filter.xml + + + + + org.wso2.carbon.identity.server.api + org.wso2.carbon.identity.api.server.debug.common + ${project.version} + + + org.wso2.carbon.identity.server.api + org.wso2.carbon.identity.api.server.common + provided + + + org.apache.cxf + cxf-rt-frontend-jaxrs + provided + + + org.apache.cxf + cxf-rt-rs-service-description + provided + + + io.swagger + swagger-jaxrs + + + com.fasterxml.jackson.core + jackson-databind + + + com.fasterxml.jackson.core + jackson-annotations + + + com.fasterxml.jackson.core + jackson-core + + + com.fasterxml.jackson.dataformat + jackson-dataformat-yaml + + + javax.ws.rs + jsr311-api + + + com.google.guava + guava + + + + + javax.ws.rs + javax.ws.rs-api + provided + + + org.wso2.carbon.identity.framework + org.wso2.carbon.identity.debug.framework + 7.10.35 + + + commons-lang.wso2 + commons-lang + 2.6.0.wso2v1 + provided + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + ${maven.compiler.plugin.version} + + 21 + 21 + + + + org.apache.maven.plugins + maven-jar-plugin + 3.3.0 + + + + + + org.codehaus.mojo + build-helper-maven-plugin + 1.8 + + + add-source + generate-sources + + add-source + + + + src/gen/java + + + + + + + + + diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApi.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApi.java new file mode 100644 index 0000000000..0d6e1cb84f --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApi.java @@ -0,0 +1,98 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1; + +import org.apache.cxf.jaxrs.ext.multipart.Attachment; +import org.apache.cxf.jaxrs.ext.multipart.Multipart; +import java.io.InputStream; +import java.util.List; + +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResponse; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResult; +import org.wso2.carbon.identity.api.server.debug.v1.model.Error; +import java.util.Map; +import org.wso2.carbon.identity.api.server.debug.v1.DebugApiService; +import org.wso2.carbon.identity.api.server.debug.v1.factories.DebugApiServiceFactory; + +import javax.validation.Valid; +import javax.ws.rs.*; +import javax.ws.rs.core.Response; +import io.swagger.annotations.*; + +import javax.validation.constraints.*; + +@Path("/debug") +@Api(description = "The debug API") + +public class DebugApi { + + private final DebugApiService delegate; + + public DebugApi() { + + this.delegate = DebugApiServiceFactory.getDebugApi(); + } + + @Valid + @GET + @Path("/{debugId}/result") + + @Produces({ "application/json" }) + @ApiOperation(value = "Get Debug Result", notes = "Retrieves the debug results for a specific debug ID. This endpoint is primarily required for multi-step debug flows, such as Identity Provider (IDP) debugging, which involve intermediate steps. For most other resources, the initial request completes the flow and this endpoint may not be needed. Scope (Permission) required: ``internal_debug_mgt_view``", response = DebugResult.class, authorizations = { + @Authorization(value = "BasicAuth"), + @Authorization(value = "OAuth2", scopes = { + @AuthorizationScope(scope = "internal_debug_mgt_view", description = "View debug sessions and results") + }) + }, tags={ "Debug", }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Debug result retrieved successfully.", response = DebugResult.class), + @ApiResponse(code = 400, message = "Bad Request", response = Error.class), + @ApiResponse(code = 401, message = "Unauthorized", response = Error.class), + @ApiResponse(code = 404, message = "Not Found", response = Error.class), + @ApiResponse(code = 500, message = "Server Error", response = Error.class) + }) + public Response getDebugResult( @Size(min=1)@ApiParam(value = "The debug session identifier.",required=true) @PathParam("debugId") String debugId) { + + return delegate.getDebugResult(debugId ); + } + + @Valid + @POST + @Path("/{resourceType}") + @Consumes({ "application/json" }) + @Produces({ "application/json" }) + @ApiOperation(value = "Start Debug Session", notes = "Initiates a debug session for supported resource types with configurable properties. Scope (Permission) required: ``internal_debug_mgt_update`` ", response = DebugResponse.class, authorizations = { + @Authorization(value = "BasicAuth"), + @Authorization(value = "OAuth2", scopes = { + @AuthorizationScope(scope = "internal_debug_mgt_update", description = "Create and manage debug sessions") + }) + }, tags={ "Debug" }) + @ApiResponses(value = { + @ApiResponse(code = 200, message = "Debug session executed successfully.", response = DebugResponse.class), + @ApiResponse(code = 400, message = "Bad Request", response = Error.class), + @ApiResponse(code = 401, message = "Unauthorized", response = Error.class), + @ApiResponse(code = 403, message = "Forbidden", response = Error.class), + @ApiResponse(code = 500, message = "Server Error", response = Error.class) + }) + public Response startDebugSession( @Size(min=1,max=50)@ApiParam(value = "Type of resource to debug. Allowed values: idp",required=true, allowableValues="idp") @PathParam("resourceType") String resourceType, @ApiParam(value = "Debug request with resource-specific properties." ) @Valid Map requestBody) { + + return delegate.startDebugSession(resourceType, requestBody ); + } + +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApiService.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApiService.java new file mode 100644 index 0000000000..130b1da2d2 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/DebugApiService.java @@ -0,0 +1,39 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1; + +import org.wso2.carbon.identity.api.server.debug.v1.*; +import org.wso2.carbon.identity.api.server.debug.v1.model.*; +import org.apache.cxf.jaxrs.ext.multipart.Attachment; +import org.apache.cxf.jaxrs.ext.multipart.Multipart; +import java.io.InputStream; +import java.util.List; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResponse; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResult; +import org.wso2.carbon.identity.api.server.debug.v1.model.Error; +import java.util.Map; +import javax.ws.rs.core.Response; + + +public interface DebugApiService { + + public Response getDebugResult(String debugId); + + public Response startDebugSession(String resourceType, Map requestBody); +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/factories/DebugApiServiceFactory.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/factories/DebugApiServiceFactory.java new file mode 100644 index 0000000000..ac7094fc4d --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/factories/DebugApiServiceFactory.java @@ -0,0 +1,32 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.factories; + +import org.wso2.carbon.identity.api.server.debug.v1.DebugApiService; +import org.wso2.carbon.identity.api.server.debug.v1.impl.DebugApiServiceImpl; + +public class DebugApiServiceFactory { + + private static final DebugApiService SERVICE = new DebugApiServiceImpl(); + + public static DebugApiService getDebugApi() { + + return SERVICE; + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResponse.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResponse.java new file mode 100644 index 0000000000..c50bbd6862 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResponse.java @@ -0,0 +1,214 @@ +/* + * Copyright (c) 2025, WSO2 LLC. (http://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.model; + +import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import javax.validation.constraints.*; + +/** + * Debug response containing generic debug information and API-curated resource-specific metadata. + **/ + +import io.swagger.annotations.*; +import java.util.Objects; +import javax.validation.Valid; +import javax.xml.bind.annotation.*; +@ApiModel(description = "Debug response containing generic debug information and API-curated resource-specific metadata.") +public class DebugResponse { + + private String debugId; + +@XmlType(name="StatusEnum") +@XmlEnum(String.class) +public enum StatusEnum { + + @XmlEnumValue("SUCCESS") SUCCESS(String.valueOf("SUCCESS")), @XmlEnumValue("SUCCESS_INCOMPLETE") SUCCESS_INCOMPLETE(String.valueOf("SUCCESS_INCOMPLETE")), @XmlEnumValue("SUCCESS_COMPLETE") SUCCESS_COMPLETE(String.valueOf("SUCCESS_COMPLETE")), @XmlEnumValue("FAILURE") FAILURE(String.valueOf("FAILURE")); + + + private String value; + + StatusEnum(String v) { + value = v; + } + + public String value() { + return value; + } + + @Override + public String toString() { + return String.valueOf(value); + } + + public static StatusEnum fromValue(String value) { + for (StatusEnum b : StatusEnum.values()) { + if (b.value.equals(value)) { + return b; + } + } + throw new IllegalArgumentException("Unexpected value '" + value + "'"); + } +} + + private StatusEnum status; + private String message; + private Map metadata = null; + + + /** + * Debug session identifier. + **/ + public DebugResponse debugId(String debugId) { + + this.debugId = debugId; + return this; + } + + @ApiModelProperty(example = "debug-496f5a3f-0094-42f2-8188-d2baa9a1287c", value = "Debug session identifier.") + @JsonProperty("debugId") + @Valid + public String getDebugId() { + return debugId; + } + public void setDebugId(String debugId) { + this.debugId = debugId; + } + + /** + * Status of the debug operation. + **/ + public DebugResponse status(StatusEnum status) { + + this.status = status; + return this; + } + + @ApiModelProperty(example = "SUCCESS", value = "Status of the debug operation.") + @JsonProperty("status") + @Valid + public StatusEnum getStatus() { + return status; + } + public void setStatus(StatusEnum status) { + this.status = status; + } + + /** + * Generic response message. + **/ + public DebugResponse message(String message) { + + this.message = message; + return this; + } + + @ApiModelProperty(example = "Debug session executed successfully", value = "Generic response message.") + @JsonProperty("message") + @Valid + public String getMessage() { + return message; + } + public void setMessage(String message) { + this.message = message; + } + + /** + * Resource-specific metadata. Includes any framework-returned fields other than top-level debugId, status, message, and success. + **/ + public DebugResponse metadata(Map metadata) { + + this.metadata = metadata; + return this; + } + + @ApiModelProperty(example = "{\"authorizationUrl\":\"https://api.asgardeo.io/t/linuka/oauth2/authorize?response_type=code&client_id=lfrTEyDGHBEUbeBKoiaosz1y8Aca&redirect_uri=https%3A%2F%2Flocalhost%3A9443%2Fcommonauth\"}", value = "Resource-specific metadata. Includes any framework-returned fields other than top-level debugId, status, message, and success.") + @JsonProperty("metadata") + @Valid + public Map getMetadata() { + return metadata; + } + public void setMetadata(Map metadata) { + this.metadata = metadata; + } + + + public DebugResponse putMetadataItem(String key, Object metadataItem) { + if (this.metadata == null) { + this.metadata = new HashMap(); + } + this.metadata.put(key, metadataItem); + return this; + } + + + + @Override + public boolean equals(java.lang.Object o) { + + if (this == o) { + return true; + } + if (o == null || getClass() != o.getClass()) { + return false; + } + DebugResponse debugResponse = (DebugResponse) o; + return Objects.equals(this.debugId, debugResponse.debugId) && + Objects.equals(this.status, debugResponse.status) && + Objects.equals(this.message, debugResponse.message) && + Objects.equals(this.metadata, debugResponse.metadata); + } + + @Override + public int hashCode() { + return Objects.hash(debugId, status, message, metadata); + } + + @Override + public String toString() { + + StringBuilder sb = new StringBuilder(); + sb.append("class DebugResponse {\n"); + + sb.append(" debugId: ").append(toIndentedString(debugId)).append("\n"); + sb.append(" status: ").append(toIndentedString(status)).append("\n"); + sb.append(" message: ").append(toIndentedString(message)).append("\n"); + sb.append(" metadata: ").append(toIndentedString(metadata)).append("\n"); + sb.append("}"); + return sb.toString(); + } + + /** + * Convert the given object to string with each line indented by 4 spaces + * (except the first line). + */ + private String toIndentedString(java.lang.Object o) { + + if (o == null) { + return "null"; + } + return o.toString().replace("\n", "\n"); + } +} + diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResult.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResult.java new file mode 100644 index 0000000000..db65bbec32 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/DebugResult.java @@ -0,0 +1,218 @@ +/* + * Copyright (c) 2025, WSO2 LLC. (http://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.model; + +import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import javax.validation.constraints.*; + +/** + * Debug response containing debugId and status and message at top level, with all protocol-specific data in metadata. + **/ + +import io.swagger.annotations.*; +import java.util.Objects; +import javax.validation.Valid; +import javax.xml.bind.annotation.*; +@ApiModel(description = "Debug response containing debugId and status and message at top level, with all protocol-specific data in metadata.") +public class DebugResult { + + private String debugId; + +@XmlType(name="StatusEnum") +@XmlEnum(String.class) +public enum StatusEnum { + + @XmlEnumValue("SUCCESS_INCOMPLETE") SUCCESS_INCOMPLETE(String.valueOf("SUCCESS_INCOMPLETE")), @XmlEnumValue("SUCCESS_COMPLETE") SUCCESS_COMPLETE(String.valueOf("SUCCESS_COMPLETE")), @XmlEnumValue("FAILURE") FAILURE(String.valueOf("FAILURE")); + + + private String value; + + StatusEnum(String v) { + value = v; + } + + public String value() { + return value; + } + + @Override + public String toString() { + return String.valueOf(value); + } + + public static StatusEnum fromValue(String value) { + for (StatusEnum b : StatusEnum.values()) { + if (b.value.equals(value)) { + return b; + } + } + throw new IllegalArgumentException("Unexpected value '" + value + "'"); + } +} + + private StatusEnum status; + private String message; + private Map metadata = null; + + + /** + * Debug session identifier. Used to retrieve debug results via the GET endpoint. + **/ + public DebugResult debugId(String debugId) { + + this.debugId = debugId; + return this; + } + + @ApiModelProperty(example = "debug-12345", required = true, value = "Debug session identifier. Used to retrieve debug results via the GET endpoint.") + @JsonProperty("debugId") + @Valid + @NotNull(message = "Property debugId cannot be null.") + + public String getDebugId() { + return debugId; + } + public void setDebugId(String debugId) { + this.debugId = debugId; + } + + /** + * Status of the debug operation. + **/ + public DebugResult status(StatusEnum status) { + + this.status = status; + return this; + } + + @ApiModelProperty(example = "SUCCESS_INCOMPLETE", required = true, value = "Status of the debug operation.") + @JsonProperty("status") + @Valid + @NotNull(message = "Property status cannot be null.") + + public StatusEnum getStatus() { + return status; + } + public void setStatus(StatusEnum status) { + this.status = status; + } + + /** + * Generic response message. + **/ + public DebugResult message(String message) { + + this.message = message; + return this; + } + + @ApiModelProperty(example = "Debug session retrieved successfully.", value = "Generic response message.") + @JsonProperty("message") + @Valid + public String getMessage() { + return message; + } + public void setMessage(String message) { + this.message = message; + } + + /** + * Protocol-specific and resource-specific debug data. For IDP OAuth debugging, includes userAttributes, mappedClaims, steps, tokens, URLs, and diagnostic information. + **/ + public DebugResult metadata(Map metadata) { + + this.metadata = metadata; + return this; + } + + @ApiModelProperty(example = "{\"debugId\":\"debug-496f5a3f-0094-42f2-8188-d2baa9a1287c\",\"status\":\"SUCCESS\",\"message\":\"Debug session retrieved successfully.\",\"metadata\":\"{...}\"}", value = "Protocol-specific and resource-specific debug data. For IDP OAuth debugging, includes userAttributes, mappedClaims, steps, tokens, URLs, and diagnostic information.") + @JsonProperty("metadata") + @Valid + public Map getMetadata() { + return metadata; + } + public void setMetadata(Map metadata) { + this.metadata = metadata; + } + + + public DebugResult putMetadataItem(String key, Object metadataItem) { + if (this.metadata == null) { + this.metadata = new HashMap(); + } + this.metadata.put(key, metadataItem); + return this; + } + + + + @Override + public boolean equals(java.lang.Object o) { + + if (this == o) { + return true; + } + if (o == null || getClass() != o.getClass()) { + return false; + } + DebugResult debugResult = (DebugResult) o; + return Objects.equals(this.debugId, debugResult.debugId) && + Objects.equals(this.status, debugResult.status) && + Objects.equals(this.message, debugResult.message) && + Objects.equals(this.metadata, debugResult.metadata); + } + + @Override + public int hashCode() { + return Objects.hash(debugId, status, message, metadata); + } + + @Override + public String toString() { + + StringBuilder sb = new StringBuilder(); + sb.append("class DebugResult {\n"); + + sb.append(" debugId: ").append(toIndentedString(debugId)).append("\n"); + sb.append(" status: ").append(toIndentedString(status)).append("\n"); + sb.append(" message: ").append(toIndentedString(message)).append("\n"); + sb.append(" metadata: ").append(toIndentedString(metadata)).append("\n"); + sb.append("}"); + return sb.toString(); + } + + /** + * Convert the given object to string with each line indented by 4 spaces + * (except the first line). + */ + private String toIndentedString(java.lang.Object o) { + + if (o == null) { + return "null"; + } + return o.toString().replace("\n", "\n"); + } +} + diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/Error.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/Error.java new file mode 100644 index 0000000000..a08df6f76f --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/gen/java/org/wso2/carbon/identity/api/server/debug/v1/model/Error.java @@ -0,0 +1,147 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.model; + +import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import javax.validation.constraints.*; + + +import io.swagger.annotations.*; +import java.util.Objects; +import javax.validation.Valid; +import javax.xml.bind.annotation.*; + +public class Error { + + private String code; + private String message; + private String description; + + /** + * An error code in DSM-prefixed format. + **/ + public Error code(String code) { + + this.code = code; + return this; + } + + @ApiModelProperty(example = "DSM-60001", required = true, value = "An error code in DSM-prefixed format.") + @JsonProperty("code") + @Valid + @NotNull(message = "Property code cannot be null.") + @Pattern(regexp="^DSM-[0-9]{5}$") + public String getCode() { + return code; + } + public void setCode(String code) { + this.code = code; + } + + /** + * An error message. + **/ + public Error message(String message) { + + this.message = message; + return this; + } + + @ApiModelProperty(example = "Invalid request.", required = true, value = "An error message.") + @JsonProperty("message") + @Valid + @NotNull(message = "Property message cannot be null.") + + public String getMessage() { + return message; + } + public void setMessage(String message) { + this.message = message; + } + + /** + * A detailed error description. + **/ + public Error description(String description) { + + this.description = description; + return this; + } + + @ApiModelProperty(example = "Request validation failed.", value = "A detailed error description.") + @JsonProperty("description") + @Valid + public String getDescription() { + return description; + } + public void setDescription(String description) { + this.description = description; + } + + + + @Override + public boolean equals(java.lang.Object o) { + + if (this == o) { + return true; + } + if (o == null || getClass() != o.getClass()) { + return false; + } + Error error = (Error) o; + return Objects.equals(this.code, error.code) && + Objects.equals(this.message, error.message) && + Objects.equals(this.description, error.description); + } + + @Override + public int hashCode() { + return Objects.hash(code, message, description); + } + + @Override + public String toString() { + + StringBuilder sb = new StringBuilder(); + sb.append("class Error {\n"); + + sb.append(" code: ").append(toIndentedString(code)).append("\n"); + sb.append(" message: ").append(toIndentedString(message)).append("\n"); + sb.append(" description: ").append(toIndentedString(description)).append("\n"); + sb.append("}"); + return sb.toString(); + } + + /** + * Convert the given object to string with each line indented by 4 spaces + * (except the first line). + */ + private String toIndentedString(java.lang.Object o) { + + if (o == null) { + return "null"; + } + return o.toString().replace("\n", "\n"); + } +} + diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/constants/DebugConstants.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/constants/DebugConstants.java new file mode 100644 index 0000000000..cf25e3b18c --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/constants/DebugConstants.java @@ -0,0 +1,90 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.constants; + +/** + * Contains constants for Debug API. + */ +public class DebugConstants { + + public static final String ERROR_CODE_PREFIX = "DSM-"; + public static final String CONNECTION_ID = "connectionId"; + + private DebugConstants() { + // Prevent instantiation. + } + + /** + * Resource type constants for debug operations. + */ + public static final class ResourceType { + + public static final String IDP = "idp"; + + private ResourceType() { + // Prevent instantiation. + } + } + + /** + * Error constants for debug flow. + */ + public enum ErrorMessage { + + // Client error codes. + ERROR_CODE_RESULT_NOT_FOUND("60002", "Debug result not found.", + "No debug result exists for the provided debug id."), + + // Server error codes. + ERROR_CODE_ERROR_PROCESSING_REQUEST("65001", "Error processing request.", + "Error occurred while processing the debug request."); + + private final String code; + private final String message; + private final String description; + + ErrorMessage(String code, String message, String description) { + + this.code = code; + this.message = message; + this.description = description; + } + + public String getCode() { + + return ERROR_CODE_PREFIX + code; + } + + public String getMessage() { + + return message; + } + + public String getDescription() { + + return description; + } + + @Override + public String toString() { + + return code + " | " + description; + } + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugService.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugService.java new file mode 100644 index 0000000000..69accba0fa --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugService.java @@ -0,0 +1,304 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.core; + +import org.apache.commons.lang.StringUtils; +import org.wso2.carbon.identity.api.server.debug.v1.constants.DebugConstants; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResponse; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResult; +import org.wso2.carbon.identity.api.server.debug.v1.model.FrameworkResponseDTO; +import org.wso2.carbon.identity.api.server.debug.v1.utils.DebugExceptionHandler; +import org.wso2.carbon.identity.debug.framework.DebugFrameworkConstants; +import org.wso2.carbon.identity.debug.framework.core.DebugRequestCoordinator; +import org.wso2.carbon.identity.debug.framework.exception.DebugFrameworkClientException; +import org.wso2.carbon.identity.debug.framework.exception.DebugFrameworkException; +import org.wso2.carbon.identity.debug.framework.exception.DebugFrameworkServerException; +import org.wso2.carbon.identity.debug.framework.model.DebugFrameworkRequest; +import org.wso2.carbon.identity.debug.framework.model.DebugFrameworkResponse; + +import java.util.Collections; +import java.util.List; +import java.util.Map; + +import javax.ws.rs.core.Response; + +/** + * Core service for debug API request handling. + */ +public class DebugService { + + // Note: Add new resource types here so that validation is applied for each request based on the resource type. + private static final Map> REQUIRED_PROPERTIES_BY_RESOURCE_TYPE = Map.of( + DebugConstants.ResourceType.IDP, List.of(DebugConstants.CONNECTION_ID)); + private final DebugRequestCoordinator coordinator; + + /** + * Constructs a new {@link DebugService} with the specified coordinator. + * + * @param coordinator The {@link DebugRequestCoordinator} used to manage debug requests. + */ + public DebugService(DebugRequestCoordinator coordinator) { + + this.coordinator = coordinator; + } + + /** + * Process a start debug session request and return a typed response DTO. + * All framework exceptions are caught here and converted to APIError. + * + * @param resourceType Path parameter resource type. + * @param requestBody Debug request payload. + * @return DebugResponse DTO. + */ + public DebugResponse processStartSession(String resourceType, Map requestBody) { + + try { + validateRequest(resourceType, requestBody); + DebugFrameworkResponse frameworkResponse = startDebugSession(resourceType, requestBody); + return buildDebugResponse(frameworkResponse); + } catch (DebugFrameworkException e) { + throw DebugExceptionHandler.handleDebugException(e); + } + } + + /** + * Process a debug result retrieval request and return a typed response DTO. + * All framework exceptions are caught here and converted to APIError. + * + * @param debugId Debug session id. + * @return DebugResult DTO. + */ + public DebugResult processGetResult(String debugId) { + + try { + validateDebugId(debugId); + DebugFrameworkResponse frameworkResponse = coordinator.getDebugResult(debugId); + return buildDebugResult(frameworkResponse, debugId); + } catch (DebugFrameworkException e) { + throw DebugExceptionHandler.handleDebugException(e); + } + } + + /** + * Builds and sends a debug request to the coordinator. + * + * @param resourceType Resource type from path parameter. + * @param properties Request properties map. + * @return DebugFrameworkResponse from the coordinator. + * @throws DebugFrameworkClientException if the framework encounters a client error. + * @throws DebugFrameworkServerException if the framework encounters a server error. + */ + private DebugFrameworkResponse startDebugSession(String resourceType, Map properties) + throws DebugFrameworkClientException, DebugFrameworkServerException { + + return coordinator.handleDebugRequest(buildDebugRequest(resourceType, properties)); + } + + private DebugFrameworkRequest buildDebugRequest(String resourceType, Map properties) { + + DebugFrameworkRequest debugRequest = new DebugFrameworkRequest(); + debugRequest.setResourceType(resourceType); + (properties != null ? properties : Collections.emptyMap()) + .forEach(debugRequest::addContextProperty); + return debugRequest; + } + + /** + * Builds a DebugResponse DTO from the typed framework response. + * The framework is responsible for providing a structured response with + * debugId, status and message as top-level fields, and metadata in getData(). + */ + private DebugResponse buildDebugResponse(DebugFrameworkResponse frameworkResponse) + throws DebugFrameworkServerException { + + if (frameworkResponse.getDebugId() == null) { + throw new DebugFrameworkServerException( + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_SERVER_ERROR.getCode(), + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_SERVER_ERROR.getMessage(), + "Debug framework response does not contain debugId."); + } + + FrameworkResponseDTO data = extractResponseData(frameworkResponse, null); + DebugResponse response = new DebugResponse(); + response.setDebugId(data.getDebugId()); + + DebugResponse.StatusEnum status = DebugStatusBuilder.resolveDebugStatus(data.getRawStatus()); + response.setStatus(status); + response.setMessage(resolveDebugMessage(status, data.getRawMessage())); + + if (data.getMetadata() != null) { + response.setMetadata(data.getMetadata()); + } + return response; + } + + /** + * Builds a DebugResult DTO from the typed framework response. + * The framework is responsible for providing a structured response with + * debugId, status and message as top-level fields, and metadata in getData(). + * + * @param frameworkResponse Framework response. + * @param requestedDebugId The originally requested debug ID (used as fallback if absent from response). + * @return DebugResult DTO. + */ + private DebugResult buildDebugResult(DebugFrameworkResponse frameworkResponse, String requestedDebugId) { + + FrameworkResponseDTO data = extractResponseData(frameworkResponse, requestedDebugId); + if (data.getDebugId() == null) { + throw DebugExceptionHandler.handleException( + Response.Status.NOT_FOUND, + DebugConstants.ErrorMessage.ERROR_CODE_RESULT_NOT_FOUND); + } + + DebugResult response = new DebugResult(); + response.setDebugId(data.getDebugId()); + + DebugResult.StatusEnum status = DebugStatusBuilder.resolveResultStatus(data.getRawStatus()); + response.setStatus(status); + response.setMessage(resolveResultMessage(status, data.getRawMessage())); + + if (data.getMetadata() != null) { + response.setMetadata(data.getMetadata()); + } + return response; + } + + /** + * Extracts common fields from a framework response into a FrameworkResponseDTO, + * using fallbackDebugId when the response does not carry its own debugId. + * + * @param frameworkResponse Framework response. + * @param fallbackDebugId Fallback debug ID (may be null). + * @return FrameworkResponseDTO holding the extracted fields. + */ + private FrameworkResponseDTO extractResponseData(DebugFrameworkResponse frameworkResponse, + String fallbackDebugId) { + + String debugId = frameworkResponse.getDebugId() != null + ? frameworkResponse.getDebugId() : fallbackDebugId; + Map data = frameworkResponse.getData(); + Map metadata = (data != null && !data.isEmpty()) ? data : null; + return new FrameworkResponseDTO(debugId, frameworkResponse.getStatus(), + frameworkResponse.getMessage(), metadata); + } + + /** + * Resolves the response message for a debug session start. + * + * @param status Resolved status enum. + * @param frameworkMessage Raw message from framework. + * @return Message string. + */ + private String resolveDebugMessage(DebugResponse.StatusEnum status, String frameworkMessage) { + + String normalizedMessage = StringUtils.trimToNull(frameworkMessage); + if (normalizedMessage != null) { + return normalizedMessage; + } + switch (status) { + case FAILURE: + return "Failed to execute the debug session."; + case SUCCESS_COMPLETE: + return "The debug session has completed successfully."; + case SUCCESS_INCOMPLETE: + return "The debug session has partially completed."; + default: + return "Debug session executed successfully."; + } + } + + /** + * Resolves the response message for a debug result retrieval. + * + * @param status Resolved status enum. + * @param frameworkMessage Raw message from framework. + * @return Message string. + */ + private String resolveResultMessage(DebugResult.StatusEnum status, String frameworkMessage) { + + String normalizedMessage = StringUtils.trimToNull(frameworkMessage); + if (normalizedMessage != null) { + return normalizedMessage; + } + switch (status) { + case SUCCESS_INCOMPLETE: + return "The debug session is still in progress."; + case SUCCESS_COMPLETE: + return "Debug session results have been retrieved successfully."; + case FAILURE: + default: + return "Failed to retrieve debug results."; + } + } + + /** + * Validates that the given debug ID is non-blank. + * + * @param debugId Debug session ID to validate. + * @throws DebugFrameworkClientException if the debug ID is blank. + */ + private void validateDebugId(String debugId) throws DebugFrameworkClientException { + + if (StringUtils.isBlank(debugId)) { + throw new DebugFrameworkClientException( + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getCode(), + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getMessage(), + "Debug ID cannot be null or empty."); + } + } + + /** + * Validates the debug start session request. + * + * @param resourceType Resource type. + * @param requestBody Request body. + * @throws DebugFrameworkClientException if validation fails. + */ + private void validateRequest(String resourceType, Map requestBody) + throws DebugFrameworkClientException { + + if (!REQUIRED_PROPERTIES_BY_RESOURCE_TYPE.containsKey(resourceType)) { + throw new DebugFrameworkClientException( + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getCode(), + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getMessage(), + String.format("Unsupported resource type: %s.", resourceType)); + } + + List requiredProperties = REQUIRED_PROPERTIES_BY_RESOURCE_TYPE.get(resourceType); + if (requiredProperties.isEmpty()) { + return; + } + + if (requestBody == null) { + throw new DebugFrameworkClientException( + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getCode(), + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getMessage(), + String.format("Debug request body cannot be null for resource type: %s.", resourceType)); + } + + for (String requiredProperty : requiredProperties) { + if (!requestBody.containsKey(requiredProperty)) { + throw new DebugFrameworkClientException( + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getCode(), + DebugFrameworkConstants.ErrorMessages.ERROR_CODE_INVALID_REQUEST.getMessage(), + String.format("Missing required property: %s.", requiredProperty)); + } + } + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugStatusBuilder.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugStatusBuilder.java new file mode 100644 index 0000000000..5902f3c07a --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/core/DebugStatusBuilder.java @@ -0,0 +1,84 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.core; + +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResponse; +import org.wso2.carbon.identity.api.server.debug.v1.model.DebugResult; + +import java.util.Locale; + +/** + * Utility class for resolving API status enums from framework status strings. + */ +public final class DebugStatusBuilder { + + private static final Log LOG = LogFactory.getLog(DebugStatusBuilder.class); + + private DebugStatusBuilder() { + // Utility class — prevent instantiation. + } + + /** + * Resolves the {@link DebugResponse.StatusEnum} from the framework status string. + * Falls back to {@link DebugResponse.StatusEnum#SUCCESS_INCOMPLETE} if the status is + * unrecognized or absent. + * + * @param status Status string from the framework response. + * @return Resolved {@link DebugResponse.StatusEnum}. + */ + public static DebugResponse.StatusEnum resolveDebugStatus(String status) { + + if (status != null) { + String normalized = status.toUpperCase(Locale.ROOT); + for (DebugResponse.StatusEnum value : DebugResponse.StatusEnum.values()) { + if (value.name().equals(normalized)) { + return value; + } + } + LOG.warn(String.format( + "Unrecognized debug status from framework: %s. Falling back to SUCCESS_INCOMPLETE.", status)); + } + return DebugResponse.StatusEnum.SUCCESS_INCOMPLETE; + } + + /** + * Resolves the {@link DebugResult.StatusEnum} from the framework status string. + * Falls back to {@link DebugResult.StatusEnum#FAILURE} if the status is + * unrecognized or absent. + * + * @param status Status string from the framework response. + * @return Resolved {@link DebugResult.StatusEnum}. + */ + public static DebugResult.StatusEnum resolveResultStatus(String status) { + + if (status != null) { + String normalized = status.toUpperCase(Locale.ROOT); + for (DebugResult.StatusEnum value : DebugResult.StatusEnum.values()) { + if (value.name().equals(normalized)) { + return value; + } + } + LOG.warn(String.format( + "Unrecognized debug status from framework: %s. Falling back to FAILURE.", status)); + } + return DebugResult.StatusEnum.FAILURE; + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/impl/DebugApiServiceImpl.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/impl/DebugApiServiceImpl.java new file mode 100644 index 0000000000..17439b25b0 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/impl/DebugApiServiceImpl.java @@ -0,0 +1,56 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.impl; + +import org.wso2.carbon.identity.api.server.debug.common.DebugServiceHolder; +import org.wso2.carbon.identity.api.server.debug.v1.DebugApiService; +import org.wso2.carbon.identity.api.server.debug.v1.core.DebugService; + +import java.util.Map; + +import javax.ws.rs.core.Response; + +/** + * Implementation of the DebugApiService interface. + */ +public class DebugApiServiceImpl implements DebugApiService { + + private final DebugService debugService; + + public DebugApiServiceImpl() { + + this.debugService = new DebugService(DebugServiceHolder.getDebugRequestCoordinator()); + } + + @Override + public Response startDebugSession(String resourceType, Map requestBody) { + + return Response.ok() + .entity(debugService.processStartSession(resourceType, requestBody)) + .build(); + } + + @Override + public Response getDebugResult(String debugId) { + + return Response.ok() + .entity(debugService.processGetResult(debugId)) + .build(); + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/model/FrameworkResponseDTO.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/model/FrameworkResponseDTO.java new file mode 100644 index 0000000000..37758ab3d2 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/model/FrameworkResponseDTO.java @@ -0,0 +1,62 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.model; + +import java.util.Map; + +/** + * Internal DTO holding common fields extracted from a DebugFrameworkResponse, + * shared between the start-session and get-result response builders. + */ +public class FrameworkResponseDTO { + + private final String debugId; + private final String rawStatus; + private final String rawMessage; + private final Map metadata; + + public FrameworkResponseDTO(String debugId, String rawStatus, String rawMessage, + Map metadata) { + + this.debugId = debugId; + this.rawStatus = rawStatus; + this.rawMessage = rawMessage; + this.metadata = metadata; + } + + public String getDebugId() { + + return debugId; + } + + public String getRawStatus() { + + return rawStatus; + } + + public String getRawMessage() { + + return rawMessage; + } + + public Map getMetadata() { + + return metadata; + } +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/utils/DebugExceptionHandler.java b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/utils/DebugExceptionHandler.java new file mode 100644 index 0000000000..c9218aa3ab --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/java/org/wso2/carbon/identity/api/server/debug/v1/utils/DebugExceptionHandler.java @@ -0,0 +1,104 @@ +/** + * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com). + * + * WSO2 LLC. licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.wso2.carbon.identity.api.server.debug.v1.utils; + +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; +import org.wso2.carbon.identity.api.server.common.error.APIError; +import org.wso2.carbon.identity.api.server.common.error.ErrorDTO; +import org.wso2.carbon.identity.api.server.debug.v1.constants.DebugConstants; +import org.wso2.carbon.identity.debug.framework.exception.DebugFrameworkClientException; +import org.wso2.carbon.identity.debug.framework.exception.DebugFrameworkException; + +import javax.ws.rs.core.Response; + +/** + * Utility class for debug API. + */ +public class DebugExceptionHandler { + + private static final Log LOG = LogFactory.getLog(DebugExceptionHandler.class); + + private DebugExceptionHandler() { + + } + + /** + * Builds an APIError from a typed ErrorMessage enum and HTTP status. + * + * @param status HTTP status. + * @param error Typed error message enum. + * @return APIError. + */ + public static APIError handleException(Response.Status status, DebugConstants.ErrorMessage error) { + + return new APIError(status, getError(error.getCode(), error.getMessage(), error.getDescription())); + } + + /** + * Builds an ErrorDTO. + * + * @param errorCode Error code. + * @param errorMessage Error message. + * @param errorDescription Error description. + * @return ErrorDTO. + */ + public static ErrorDTO getError(String errorCode, String errorMessage, String errorDescription) { + + ErrorDTO error = new ErrorDTO(); + error.setCode(errorCode); + error.setMessage(errorMessage); + error.setDescription(errorDescription); + return error; + } + + /** + * Handles a DebugFrameworkException by mapping it to an APIError. + * + * @param e Debug framework exception. + * @return APIError with the appropriate HTTP status and error details. + */ + public static APIError handleDebugException(DebugFrameworkException e) { + + Response.Status status; + if (e instanceof DebugFrameworkClientException) { + LOG.debug(e.getMessage(), e); + status = Response.Status.BAD_REQUEST; + } else { + LOG.error(e.getMessage(), e); + status = Response.Status.INTERNAL_SERVER_ERROR; + } + + String errorCode = e.getErrorCode(); + if (errorCode == null) { + errorCode = DebugConstants.ErrorMessage.ERROR_CODE_ERROR_PROCESSING_REQUEST.getCode(); + } else if (!errorCode.startsWith(DebugConstants.ERROR_CODE_PREFIX)) { + errorCode = DebugConstants.ERROR_CODE_PREFIX + errorCode; + } + + return handleException(status, errorCode, e.getMessage(), e.getDescription()); + } + + private static APIError handleException(Response.Status status, String errorCode, + String message, String description) { + + return new APIError(status, getError(errorCode, message, description)); + } + +} diff --git a/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/resources/debug.yaml b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/resources/debug.yaml new file mode 100644 index 0000000000..774beb4a57 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/org.wso2.carbon.identity.api.server.debug.v1/src/main/resources/debug.yaml @@ -0,0 +1,266 @@ +openapi: 3.0.0 +info: + version: "1.0" + title: WSO2 Identity Server - Debug API + description: > + The Debug REST API provides a centralized interface to initiate and retrieve + debug sessions within the WSO2 Identity Server. This API enables developers + and administrators to troubleshoot supported resource types efficiently through + controlled debug workflows. + contact: + name: WSO2 + url: 'https://wso2.com/identity-platform/' + email: architecture@wso2.org + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + +security: + - OAuth2: [] + - BasicAuth: [] + +servers: + - url: "/t/{tenant-domain}/api/server/v1" + variables: + tenant-domain: + default: "carbon.super" + description: "The tenant domain." + +paths: + /debug/{resourceType}: + post: + summary: "Start Debug Session" + description: "Initiates a debug session for supported resource types with configurable properties.\n\n + Scope (Permission) required: ``internal_debug_mgt_update``\n\n" + operationId: "startDebugSession" + tags: + - "Debug" + security: + - OAuth2: [internal_debug_mgt_update] + - BasicAuth: [] + parameters: + - name: "resourceType" + in: "path" + description: "Type of resource to debug. Allowed values: idp" + required: true + schema: + type: "string" + enum: ["idp"] + minLength: 1 + maxLength: 50 + example: "idp" + requestBody: + description: "Debug request with resource-specific properties." + content: + application/json: + schema: + type: object + description: "Resource-specific properties for the selected resource type." + additionalProperties: + type: string + minLength: 1 + maxLength: 255 + example: + connectionId: "11cb1448-2c30-4f9f-af8e-f82be20e0bbf" + responses: + '200': + description: "Debug session executed successfully." + content: + application/json: + schema: + $ref: "#/components/schemas/DebugResponse" + '400': + description: "Bad Request" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: "DSM-60001" + message: "Invalid request." + description: "Request validation failed." + '401': + description: "Unauthorized" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + '403': + description: "Forbidden" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + '500': + description: "Server Error" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: "DSM-65001" + message: "Error processing request." + description: "Error occurred while processing the debug request." + + /debug/{debugId}/result: + get: + summary: "Get Debug Result" + description: "Retrieves the debug results for a specific debug ID. This endpoint is primarily required for multi-step debug flows, such as Identity Provider (IDP) debugging, which involve intermediate steps. For most other resources, the initial request completes the flow and this endpoint may not be needed.\n\n + Scope (Permission) required: ``internal_debug_mgt_view``" + operationId: "getDebugResult" + tags: + - "Debug" + security: + - OAuth2: [internal_debug_mgt_view] + - BasicAuth: [] + parameters: + - name: "debugId" + in: "path" + description: "The debug session identifier." + required: true + schema: + type: "string" + minLength: 1 + responses: + '200': + description: "Debug result retrieved successfully." + content: + application/json: + schema: + $ref: "#/components/schemas/DebugResult" + '400': + description: "Bad Request" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: "DSM-60001" + message: "Invalid request." + description: "Request validation failed." + '401': + description: "Unauthorized" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + '404': + description: "Not Found" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: "DSM-60002" + message: "Debug result not found." + description: "No debug result exists for the provided session id." + '500': + description: "Server Error" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: "DSM-65001" + message: "Error processing request." + description: "Error occurred while processing the debug request." + +components: + securitySchemes: + BasicAuth: + type: http + scheme: basic + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://localhost:9443/oauth2/authorize + tokenUrl: https://localhost:9443/oauth2/token + scopes: + internal_debug_mgt_view: View debug sessions and results + internal_debug_mgt_update: Create and manage debug sessions + + schemas: + + # ------------- + # Common Error + # ------------- + Error: + type: "object" + required: + - code + - message + properties: + code: + type: string + pattern: "^DSM-[0-9]{5}$" + example: "DSM-60001" + description: "An error code in DSM-prefixed format." + message: + type: string + example: "Invalid request." + description: "An error message." + description: + type: string + example: "Request validation failed." + description: "A detailed error description." + + # --------------------------------- + # Debug Request/Response Models + # --------------------------------- + DebugResponse: + type: object + description: "Debug response containing generic debug information and API-curated resource-specific metadata." + properties: + debugId: + type: string + description: "Debug session identifier." + example: "debug-496f5a3f-0094-42f2-8188-d2baa9a1287c" + status: + type: string + description: "Status of the debug operation." + enum: ["SUCCESS", "SUCCESS_INCOMPLETE", "SUCCESS_COMPLETE", "FAILURE"] + example: "SUCCESS" + message: + type: string + description: "Generic response message." + example: "Debug session executed successfully" + metadata: + type: object + description: "Resource-specific metadata. Includes any framework-returned fields other than top-level debugId, status, message, and success." + additionalProperties: true + example: + authorizationUrl: "https://api.asgardeo.io/t/linuka/oauth2/authorize?response_type=code&client_id=lfrTEyDGHBEUbeBKoiaosz1y8Aca&redirect_uri=https%3A%2F%2Flocalhost%3A9443%2Fcommonauth" + + # ----------------------------- + # GET /debug/{debugId}/result + # ----------------------------- + DebugResult: + type: object + required: + - debugId + - status + description: "Debug response containing debugId and status and message at top level, with all protocol-specific data in metadata." + properties: + debugId: + type: string + description: "Debug session identifier. Used to retrieve debug results via the GET endpoint." + example: "debug-12345" + status: + type: string + description: "Status of the debug operation." + enum: ["SUCCESS_INCOMPLETE", "SUCCESS_COMPLETE", "FAILURE"] + example: "SUCCESS_INCOMPLETE" + message: + type: string + description: "Generic response message." + example: "Debug session retrieved successfully." + metadata: + type: object + description: "Protocol-specific and resource-specific debug data. For IDP OAuth debugging, includes userAttributes, mappedClaims, steps, tokens, URLs, and diagnostic information." + additionalProperties: true + example: + debugId: "debug-496f5a3f-0094-42f2-8188-d2baa9a1287c" + status: "SUCCESS" + "message": "Debug session retrieved successfully." + "metadata": "{...}" diff --git a/components/org.wso2.carbon.identity.api.server.debug/pom.xml b/components/org.wso2.carbon.identity.api.server.debug/pom.xml new file mode 100644 index 0000000000..3fd61a9a46 --- /dev/null +++ b/components/org.wso2.carbon.identity.api.server.debug/pom.xml @@ -0,0 +1,45 @@ + + + + + 4.0.0 + + + identity-api-server + org.wso2.carbon.identity.server.api + 1.5.18-SNAPSHOT + ../../pom.xml + + + org.wso2.carbon.identity.api.server.debug + 1.5.18-SNAPSHOT + pom + WSO2 Identity Server - Debug + WSO2 Identity Server - REST API for Debug + + + ${project.basedir}/../../../findbugs-exclude-filter.xml + + + + org.wso2.carbon.identity.api.server.debug.common + org.wso2.carbon.identity.api.server.debug.v1 + + + diff --git a/pom.xml b/pom.xml index a160f0325f..b7b47cc43a 100644 --- a/pom.xml +++ b/pom.xml @@ -1215,6 +1215,7 @@ components/org.wso2.carbon.identity.api.server.asynchronous.operation.status.management components/org.wso2.carbon.identity.api.server.vc.template.management components/org.wso2.carbon.identity.api.server.credential.management + components/org.wso2.carbon.identity.api.server.debug components/org.wso2.carbon.identity.api.server.moesif.publisher