Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 35 additions & 9 deletions apps/customer-portal/backend-v2/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,19 @@ responses for the frontend. This is a Go rewrite of the Ballerina backend at
`apps/customer-portal/backend`, modeled on `apps/csm-portal/backend`'s conventions — read that
backend's own CLAUDE.md too if something here is underspecified.

**Status: in progress.** 16 routes are wired up so far (`GET /health`, `GET`/`PATCH /users/me`,
**Status: in progress.** 26 routes are wired up so far (`GET /health`, `GET`/`PATCH /users/me`,
`POST /accounts/search`, `GET /accounts/{id}`, `POST /projects/search`, `GET /projects/{id}`,
`POST /cases/search`, `GET /cases/{id}`, `POST /cases`, `PATCH /cases/{id}`,
`POST /cases/{id}/comments`, `POST /deployments/search`, `POST /deployments`,
`GET /updates/product-update-levels`, `POST /updates/levels/search`) across three upstream
services: entity-service, the WSO2 Updates service, and SCIM. The Ballerina backend exposes ~100
routes across many more modules (deployed products, attachments, comments, conversations, change
requests, call requests, catalogs, time cards, registry tokens, contacts, escalations, product
vulnerabilities, AI chat/websocket, etc.) — none of those are ported yet. Follow the recipe below
to add the next one.
`POST /cases/{id}/comments`, `POST /cases/{id}/activities/search`, `POST /deployments/search`,
`POST /deployments`, `POST /deployed-products/search`, `POST /deployed-products`,
`PATCH /deployed-products/{id}`, `POST /attachments`, `POST /attachments/search`,
`GET /attachments/{id}/content`, `DELETE /attachments/{id}`, `POST /products/search`,
`POST /products/{id}/versions/search`, `GET /updates/product-update-levels`,
`POST /updates/levels/search`) across three upstream services: entity-service, the WSO2 Updates
service, and SCIM. The Ballerina backend exposes ~100 routes across many more modules (generic
comments, conversations, change requests, call requests, catalogs, time cards, registry tokens,
contacts, escalations, product vulnerabilities, AI chat/websocket, etc.) — none of those are ported
yet. Follow the recipe below to add the next one.

## Which entity-service

Expand Down Expand Up @@ -99,7 +102,30 @@ a genuine advantage of the DTO-mapping convention over raw passthrough — `apps
has to model this as an OpenAPI `oneOf` in its spec and pass the ambiguity on to the frontend;
here, it's resolved once in the mapper. Also deliberately excluded from account DTOs: `ArrToday`
(annual recurring revenue — WSO2-internal financial data, never expose to the customer) and `Pod`
(WSO2-internal account routing).
(WSO2-internal account routing). `POST /products/search` and `POST /products/{id}/versions/search`
(`internal/entity/types.go`'s `ProductView`/`ProductVersionView`) use the exact same superset-struct
technique — e.g. `ProductVersionView.ReleaseDate` is typed `*string` even though the Postgres shape
is `time.Time` and the ServiceNow shape is a plain string, because a Go `*string` field decodes a
JSON string value regardless of which the source type actually was.

**`json.RawMessage` on a request field usually means "preserve three states," not "skip validation."**
`entity.UpdateDeployedProductRequest.Description` is `json.RawMessage` specifically so entity-service
can distinguish "field absent" (omit), `"description": null` (clear the value), and
`"description": "value"` (set it) — a plain `*string` can't represent "absent vs. explicitly null."
When a portal request decodes straight into a struct with such a field (no restricted DTO needed
here, since Cores/TPS/Description/Active are all customer-appropriate), the raw bytes the client
sent pass through unchanged and this three-state semantic is preserved automatically — don't
"simplify" the field to `*string` when porting a similar endpoint.

**Binary responses use a `doBinary`-shaped client method, not `getJSON`/`postJSON`.**
`GET /attachments/{id}/content` returns a raw file, not JSON — `entity.Client.doBinary` (added in
`internal/entity/client.go` alongside `do`) returns `(body []byte, contentType string, error)`, and
the handler (`internal/handler/attachments.go`) writes `Content-Type` from entity-service's own
(already-sanitized) header value and explicitly sets `Content-Disposition: attachment` itself —
never render an attachment inline, since entity-service's own allowlist coercion to
`application/octet-stream` for unrecognized types is a stored-XSS mitigation this backend must not
undo by, say, echoing a client-supplied filename into a `Content-Disposition` you construct
yourself.

Request bodies are usually the exception: incoming search/filter/create payloads are decoded
directly into the entity package's request structs (e.g. `entity.SearchProjectsRequest`,
Expand Down
65 changes: 60 additions & 5 deletions apps/customer-portal/backend-v2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Go rewrite of the Ballerina backend at `apps/customer-portal/backend`. It is a b
[`entity-service`](../../../entity-service) (this repo's `cs-tools/entity-service`, not the
`digiops-cs/entity-service` the Ballerina backend targets), and shapes the responses for the frontend.

This is a work in progress — only the 16 routes listed below are implemented so far, across
This is a work in progress — only the 26 routes listed below are implemented so far, across
entity-service, the WSO2 Updates service, and SCIM. Everything else the Ballerina backend exposes
still needs a Go handler; add them following the pattern described in
[CLAUDE.md](./CLAUDE.md#adding-a-new-endpoint).
Expand Down Expand Up @@ -133,8 +133,11 @@ backend-v2/
│ │ ├── users.go # GetMe, PatchMe
│ │ ├── accounts.go # SearchAccounts, GetAccount
│ │ ├── projects.go # SearchProjects, GetProject
│ │ ├── cases.go # SearchCases, GetCase, CreateCase, UpdateCase, CreateCaseComment
│ │ └── deployments.go # SearchDeployments, CreateDeployment
│ │ ├── cases.go # SearchCases, GetCase, CreateCase, UpdateCase, CreateCaseComment, SearchCaseActivities
│ │ ├── deployments.go # SearchDeployments, CreateDeployment
│ │ ├── deployed_products.go # SearchDeployedProducts, CreateDeployedProduct, UpdateDeployedProduct
│ │ ├── attachments.go # CreateAttachment, SearchAttachments, GetAttachmentContent, DeleteAttachment
│ │ └── products.go # SearchProducts, SearchProductVersions
│ ├── updates/ # OAuth2 HTTP client for the WSO2 Updates service
│ │ ├── client.go # Config/Client/do()
│ │ ├── types.go # upstream (snake_case) vs portal (camelCase) structs
Expand All @@ -149,7 +152,10 @@ backend-v2/
│ │ ├── account.go
│ │ ├── project.go
│ │ ├── case.go
│ │ └── deployment.go
│ │ ├── deployment.go
│ │ ├── deployed_product.go
│ │ ├── attachment.go
│ │ └── product.go
│ ├── middleware/
│ │ ├── auth.go # JWT validation; injects UserInfo into context
│ │ ├── correlation.go # X-CSM-Correlation-ID propagation + slog enrichment
Expand All @@ -160,8 +166,11 @@ backend-v2/
│ ├── users.go # GET/PATCH /users/me
│ ├── accounts.go # POST /accounts/search, GET /accounts/{id}
│ ├── projects.go # POST /projects/search, GET /projects/{id}
│ ├── cases.go # cases search/get/create/update/comment
│ ├── cases.go # cases search/get/create/update/comment/activities
│ ├── deployments.go # POST /deployments/search, POST /deployments
│ ├── deployed_products.go # deployed-product search/create/update
│ ├── attachments.go # attachment create/search/download/delete
│ ├── products.go # POST /products/search, POST /products/{id}/versions/search
│ └── updates.go # GET /updates/product-update-levels, POST /updates/levels/search
├── .choreo/component.yaml
├── openapi.yaml
Expand All @@ -186,6 +195,16 @@ backend-v2/
- `POST /cases/{id}/comments` — add a comment to a case (always a plain customer comment)
- `POST /deployments/search` — search deployments
- `POST /deployments` — create a deployment (ServiceNow data source only)
- `POST /deployed-products/search` — search deployed products
- `POST /deployed-products` — create a deployed product (ServiceNow data source only)
- `PATCH /deployed-products/{id}` — update a deployed product's cores/tps/description, or deactivate it (ServiceNow data source only)
- `POST /attachments` — create an attachment
- `POST /attachments/search` — search attachments
- `GET /attachments/{id}/content` — download an attachment's raw file content
- `DELETE /attachments/{id}` — delete an attachment
- `POST /cases/{id}/activities/search` — search a case's activity feed (comments, attachments, field changes)
- `POST /products/search` — search products
- `POST /products/{id}/versions/search` — search a product's versions
- `GET /updates/product-update-levels` — list product update levels
- `POST /updates/levels/search` — search update descriptions between two update levels

Expand Down Expand Up @@ -254,6 +273,42 @@ curl -X POST http://localhost:8080/deployments \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"projectId":"<project-id>","name":"Production"}'

curl -X POST http://localhost:8080/deployed-products/search \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"pagination":{"limit":10,"offset":0},"deploymentIds":["<deployment-id>"]}'

curl -X POST http://localhost:8080/deployed-products \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"projectId":"<project-id>","deploymentId":"<deployment-id>","productId":"<product-id>","versionId":"<version-id>"}'

curl -X PATCH http://localhost:8080/deployed-products/<deployed-product-id> \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"cores":4}'

curl -X POST http://localhost:8080/attachments \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"referenceId":"<case-id>","referenceType":"case","name":"log.txt","type":"text/plain","file":"<base64>"}'

curl -X POST http://localhost:8080/attachments/search \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"referenceId":"<case-id>","referenceType":"case","pagination":{"limit":10,"offset":0}}'

curl -H "x-jwt-assertion: $JWT" http://localhost:8080/attachments/<attachment-id>/content -o downloaded-file

curl -X DELETE -H "x-jwt-assertion: $JWT" http://localhost:8080/attachments/<attachment-id>

curl -X POST http://localhost:8080/cases/<case-id>/activities/search \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"pagination":{"limit":20,"offset":0}}'

curl -X POST http://localhost:8080/products/search \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"pagination":{"limit":10,"offset":0},"searchQuery":"wso2am"}'

curl -X POST http://localhost:8080/products/<product-id>/versions/search \
-H "x-jwt-assertion: $JWT" -H "Content-Type: application/json" \
-d '{"pagination":{"limit":10,"offset":0}}'

curl -H "x-jwt-assertion: $JWT" http://localhost:8080/updates/product-update-levels

curl -X POST http://localhost:8080/updates/levels/search \
Expand Down
18 changes: 18 additions & 0 deletions apps/customer-portal/backend-v2/cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,9 @@ func main() {
projectHandler := handler.NewProjectHandler(entityClient)
caseHandler := handler.NewCaseHandler(entityClient)
deploymentHandler := handler.NewDeploymentHandler(entityClient)
deployedProductHandler := handler.NewDeployedProductHandler(entityClient)
attachmentHandler := handler.NewAttachmentHandler(entityClient)
productHandler := handler.NewProductHandler(entityClient)
accountHandler := handler.NewAccountHandler(entityClient)
updatesHandler := handler.NewUpdatesHandler(updatesClient)

Expand Down Expand Up @@ -109,12 +112,27 @@ func main() {
mux.HandleFunc("POST /cases", caseHandler.CreateCase)
mux.HandleFunc("PATCH /cases/{id}", caseHandler.PatchCase)
mux.HandleFunc("POST /cases/{id}/comments", caseHandler.CreateCaseComment)
mux.HandleFunc("POST /cases/{id}/activities/search", caseHandler.SearchCaseActivities)

mux.HandleFunc("POST /deployments/search", deploymentHandler.SearchDeployments)
// POST /deployments only succeeds against entity-service's ServiceNow
// data source — see internal/entity/deployments.go.
mux.HandleFunc("POST /deployments", deploymentHandler.CreateDeployment)

mux.HandleFunc("POST /deployed-products/search", deployedProductHandler.SearchDeployedProducts)
// POST/PATCH /deployed-products only succeed against entity-service's
// ServiceNow data source — see internal/entity/deployed_products.go.
mux.HandleFunc("POST /deployed-products", deployedProductHandler.CreateDeployedProduct)
mux.HandleFunc("PATCH /deployed-products/{id}", deployedProductHandler.PatchDeployedProduct)

mux.HandleFunc("POST /attachments", attachmentHandler.CreateAttachment)
mux.HandleFunc("POST /attachments/search", attachmentHandler.SearchAttachments)
mux.HandleFunc("GET /attachments/{id}/content", attachmentHandler.GetAttachmentContent)
mux.HandleFunc("DELETE /attachments/{id}", attachmentHandler.DeleteAttachment)

mux.HandleFunc("POST /products/search", productHandler.SearchProducts)
mux.HandleFunc("POST /products/{id}/versions/search", productHandler.SearchProductVersions)

mux.HandleFunc("POST /accounts/search", accountHandler.SearchAccounts)
mux.HandleFunc("GET /accounts/{id}", accountHandler.GetAccount)

Expand Down
102 changes: 102 additions & 0 deletions apps/customer-portal/backend-v2/internal/dto/attachment.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
// 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 dto

import (
"time"

"github.com/wso2-open-operations/cs-tools/apps/customer-portal/backend-v2/internal/entity"
)

// AttachmentCreateResponse is the portal's response for POST /attachments.
type AttachmentCreateResponse struct {
ID string `json:"id"`
SizeBytes int `json:"sizeBytes"`
CreatedOn time.Time `json:"createdOn"`
DownloadURL string `json:"downloadUrl"`
}

// MapAttachmentCreate builds the portal response from entity-service's CreateAttachmentResponse.
func MapAttachmentCreate(r entity.CreateAttachmentResponse) AttachmentCreateResponse {
return AttachmentCreateResponse{
ID: r.Attachment.ID,
SizeBytes: r.Attachment.SizeBytes,
CreatedOn: r.Attachment.CreatedOn,
DownloadURL: r.Attachment.DownloadURL,
}
}

// AttachmentSummary is one item of the portal's response for POST /attachments/search.
type AttachmentSummary struct {
ID string `json:"id"`
ReferenceID string `json:"referenceId"`
ReferenceType string `json:"referenceType"`
Name string `json:"name"`
Type string `json:"type"`
SizeBytes int `json:"sizeBytes"`
Description *string `json:"description,omitempty"`
CreatedBy string `json:"createdBy"`
CreatedOn time.Time `json:"createdOn"`
DownloadURL *string `json:"downloadUrl,omitempty"`
PreviewURL *string `json:"previewUrl,omitempty"`
}

// SearchAttachmentsResponse is the portal's response for POST /attachments/search.
type SearchAttachmentsResponse struct {
Attachments []AttachmentSummary `json:"attachments"`
Total int `json:"total"`
Limit int `json:"limit"`
Offset int `json:"offset"`
HasMore bool `json:"hasMore"`
}

// MapSearchAttachments builds the portal response from entity-service's SearchAttachmentsResponse.
func MapSearchAttachments(r entity.SearchAttachmentsResponse) SearchAttachmentsResponse {
items := make([]AttachmentSummary, 0, len(r.Attachments))
for _, a := range r.Attachments {
items = append(items, AttachmentSummary{
ID: a.ID,
ReferenceID: a.ReferenceID,
ReferenceType: string(a.ReferenceType),
Name: a.Name,
Type: a.Type,
SizeBytes: a.SizeBytes,
Description: a.Description,
CreatedBy: a.CreatedBy,
CreatedOn: a.CreatedOn,
DownloadURL: a.DownloadURL,
PreviewURL: a.PreviewURL,
})
}
return SearchAttachmentsResponse{
Attachments: items,
Total: r.Total,
Limit: r.Limit,
Offset: r.Offset,
HasMore: r.HasMore,
}
}

// DeleteResponse is the portal's response for DELETE /attachments/{id}.
type DeleteResponse struct {
Message string `json:"message"`
}

// MapDeleteAttachment builds the portal response from entity-service's DeleteAttachmentResponse.
func MapDeleteAttachment(r entity.DeleteAttachmentResponse) DeleteResponse {
return DeleteResponse{Message: r.Message}
}
Loading