Add receive v1 json schemas to swagger

This is done with a custom script to embed the schemas from signal-cli into the docs.go file

Dockerfile

@@ -87,7 +87,8 @@ RUN if [ "$(uname -m)" = "x86_64" ]; then \
 		&& zip -qu libsignal-client.jar libsignal_jni.so \
 		&& cd /tmp/signal-cli-${SIGNAL_CLI_VERSION}-source \
 		&& git apply /tmp/signal-cli-native.patch \
-		&& ./gradlew -q nativeCompile; \
+		&& ./gradlew -q nativeCompile \
+		&& ./gradlew jsonSchemas; \
 	elif [ "$(uname -m)" = "aarch64" ] ; then \
 		echo "Use native image from @morph027 (https://packaging.gitlab.io/signal-cli/) for arm64 - many thanks to @morph027" \
 		&& curl -fsSL https://packaging.gitlab.io/signal-cli/gpg.key | gpg -o /usr/share/keyrings/signal-cli-native.pgp --dearmor \
@@ -152,6 +153,10 @@ RUN cd /tmp/signal-cli-rest-api-src/scripts && go build -o jsonrpc2-helper
 # build plugin_loader
 RUN cd /tmp/signal-cli-rest-api-src && go build -buildmode=plugin -o signal-cli-rest-api_plugin_loader.so plugin_loader.go
 
+# Manually add the json schemas for the receive V1 endpoint
+RUN cd /tmp/signal-cli-rest-api-src/src/docs \
+    && go run update_receive_docs.go /tmp/signal-cli-${SIGNAL_CLI_VERSION}-source/build/generated/META-INF/schemas
+
 # Start a fresh container for release container
 
 # eclipse-temurin doesn't provide a OpenJDK 21 image for armv7 (see https://github.com/adoptium/containers/issues/502). Until this

src/docs/README.md

@@ -21,6 +21,14 @@ Regenerate the files with your local source code changes.
         ```bash
         swag init --requiredByDefault
         ```
+1. Set the current working dir to `src/docs`
+    ```bash
+    cd docs
+    ```
+1. Run the script to add the receive V1 schemas
+    ```bash
+    go run add_v1_receive_schemas.go
+    ```
 
 ## Run the web server
 

src/docs/add_v1_receive_schemas.go

@@ -0,0 +1,369 @@
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+
+	_ "github.com/bbernhard/signal-cli-rest-api/docs"
+)
+
+const (
+	docsPath       = "docs.go"
+	openMarker     = "const docTemplate = `"
+	closeMarker    = "`\n\n// SwaggerInfo"
+	definitionsKey = `"definitions": {`
+	receivePrefix  = "receive."
+	receivePathKey = `"/v1/receive/{number}":`
+	receiveWrapper = "data.Message"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		fmt.Fprintf(os.Stderr, "usage: go run update_receive_docs.go <receiveDir>\n")
+		os.Exit(1)
+	}
+	receiveDir := os.Args[1]
+
+	if err := run(receiveDir); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run(receiveDir string) error {
+	content, err := os.ReadFile(docsPath)
+	if err != nil {
+		return fmt.Errorf("read %s: %w", docsPath, err)
+	}
+
+	template, err := extractDocTemplate(string(content))
+	if err != nil {
+		return err
+	}
+
+	definitions := make(map[string]interface{})
+
+	titleByFile, err := addReceiveSchemas(definitions, receiveDir)
+	if err != nil {
+		return err
+	}
+
+	if err := updateReceiveSchemaRefs(definitions, titleByFile); err != nil {
+		return err
+	}
+
+	addEnvelopeWrapperDefinition(definitions)
+
+	newEntries, err := renderManagedDefinitions(definitions)
+	if err != nil {
+		return err
+	}
+
+	updatedTemplate, err := appendDefinitionsEntries(template, newEntries)
+	if err != nil {
+		return err
+	}
+
+	updatedTemplate, err = replaceReceiveResponseSchema(updatedTemplate)
+	if err != nil {
+		return err
+	}
+
+	updated := strings.Replace(string(content), template, updatedTemplate, 1)
+
+	if err := os.WriteFile(docsPath, []byte(updated), 0644); err != nil {
+		return fmt.Errorf("write %s: %w", docsPath, err)
+	}
+
+	fmt.Printf("updated %s\n", docsPath)
+	return nil
+}
+
+func extractDocTemplate(content string) (string, error) {
+	start := strings.Index(content, openMarker)
+	if start == -1 {
+		return "", fmt.Errorf("could not find docTemplate start in %s", docsPath)
+	}
+
+	start += len(openMarker)
+	endOffset := strings.Index(content[start:], closeMarker)
+	if endOffset == -1 {
+		return "", fmt.Errorf("could not find docTemplate end in %s", docsPath)
+	}
+
+	return content[start : start+endOffset], nil
+}
+
+func definitionsBounds(template string) (int, int, error) {
+	definitionsIndex := strings.Index(template, definitionsKey)
+	if definitionsIndex == -1 {
+		return -1, -1, fmt.Errorf("could not find definitions block in docTemplate")
+	}
+
+	braceIndex := definitionsIndex + strings.Index(definitionsKey, "{")
+	closingBraceIndex, err := findMatchingBrace(template, braceIndex)
+	if err != nil {
+		return -1, -1, err
+	}
+
+	return braceIndex, closingBraceIndex, nil
+}
+
+func appendDefinitionsEntries(template string, entries string) (string, error) {
+	braceIndex, closingBraceIndex, err := definitionsBounds(template)
+	if err != nil {
+		return "", err
+	}
+
+	definitionsBlock := template[braceIndex : closingBraceIndex+1]
+	if strings.Contains(definitionsBlock, `"`+receiveWrapper+`"`) || strings.Contains(definitionsBlock, `"`+receivePrefix) {
+		return "", fmt.Errorf("definitions already contain receive entries; run swag init first")
+	}
+
+	inner := strings.TrimSpace(template[braceIndex+1 : closingBraceIndex])
+
+	if inner == "" {
+		return template[:braceIndex+1] + "\n" + entries + "\n" + template[closingBraceIndex:], nil
+	}
+
+	closingLine := "\n    }"
+	insertIndex := strings.LastIndex(template[:closingBraceIndex+1], closingLine)
+	if insertIndex == -1 {
+		return "", fmt.Errorf("could not determine definitions closing line")
+	}
+
+	return template[:insertIndex] + ",\n" + entries + template[insertIndex:], nil
+}
+
+func addReceiveSchemas(definitions map[string]interface{}, receiveDir string) (map[string]string, error) {
+	entries, err := os.ReadDir(receiveDir)
+	if err != nil {
+		return nil, fmt.Errorf("read %s: %w", receiveDir, err)
+	}
+
+	files := make([]string, 0)
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".schema.json") {
+			continue
+		}
+		files = append(files, entry.Name())
+	}
+	sort.Strings(files)
+	titleByFile := make(map[string]string, len(files))
+
+	for _, name := range files {
+		fullPath := filepath.Join(receiveDir, name)
+		data, err := os.ReadFile(fullPath)
+		if err != nil {
+			return nil, fmt.Errorf("read schema file %s: %w", fullPath, err)
+		}
+
+		var schemaObj map[string]interface{}
+		if err := json.Unmarshal(data, &schemaObj); err != nil {
+			return nil, fmt.Errorf("parse schema file %s: %w", fullPath, err)
+		}
+
+		title, ok := schemaObj["title"].(string)
+		if !ok || strings.TrimSpace(title) == "" {
+			return nil, fmt.Errorf("schema file %s is missing title", fullPath)
+		}
+
+		titleByFile[name] = title
+		definitions[receivePrefix+title] = removeSchemaKeysRecursive(schemaObj, "")
+	}
+
+	return titleByFile, nil
+}
+
+func removeSchemaKeysRecursive(value interface{}, parentKey string) interface{} {
+	switch typed := value.(type) {
+	case map[string]interface{}:
+		updated := make(map[string]interface{}, len(typed))
+		for key, item := range typed {
+			if key == "$schema" || key == "$id" {
+				continue
+			}
+			if key == "title" && parentKey != "properties" {
+				continue
+			}
+			updated[key] = removeSchemaKeysRecursive(item, key)
+		}
+		return updated
+	case []interface{}:
+		updated := make([]interface{}, len(typed))
+		for idx, item := range typed {
+			updated[idx] = removeSchemaKeysRecursive(item, parentKey)
+		}
+		return updated
+	default:
+		return value
+	}
+}
+
+func updateReceiveSchemaRefs(definitions map[string]interface{}, titleByFile map[string]string) error {
+	for key, value := range definitions {
+		if !strings.HasPrefix(key, receivePrefix) {
+			continue
+		}
+		definitions[key] = rewriteSchemaRefs(value, titleByFile)
+	}
+
+	return nil
+}
+
+func rewriteSchemaRefs(value interface{}, titleByFile map[string]string) interface{} {
+	switch typed := value.(type) {
+	case map[string]interface{}:
+		updated := make(map[string]interface{}, len(typed))
+		for k, v := range typed {
+			if k == "$ref" {
+				if refValue, ok := v.(string); ok {
+					if strings.HasSuffix(refValue, ".schema.json") {
+						base := filepath.Base(refValue)
+						if title, exists := titleByFile[base]; exists {
+							updated[k] = "#/definitions/" + receivePrefix + title
+							continue
+						}
+					}
+				}
+			}
+
+			updated[k] = rewriteSchemaRefs(v, titleByFile)
+		}
+		return updated
+	case []interface{}:
+		updated := make([]interface{}, len(typed))
+		for idx, item := range typed {
+			updated[idx] = rewriteSchemaRefs(item, titleByFile)
+		}
+		return updated
+	default:
+		return value
+	}
+}
+
+func addEnvelopeWrapperDefinition(definitions map[string]interface{}) {
+	definitions[receiveWrapper] = map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"account":  map[string]interface{}{"type": "string"},
+			"envelope": map[string]interface{}{"$ref": "#/definitions/receive.MessageEnvelope"},
+		},
+		"required": []interface{}{"account", "envelope"},
+	}
+}
+
+func renderManagedDefinitions(definitions map[string]interface{}) (string, error) {
+	keys := make([]string, 0, len(definitions))
+	for key := range definitions {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	parts := make([]string, 0, len(keys))
+	for _, key := range keys {
+		raw, err := json.MarshalIndent(definitions[key], "", "    ")
+		if err != nil {
+			return "", fmt.Errorf("marshal definition %s: %w", key, err)
+		}
+
+		lines := strings.Split(string(raw), "\n")
+		for idx := range lines {
+			lines[idx] = "        " + lines[idx]
+		}
+
+		entry := "        " + strconv.Quote(key) + ": " + strings.TrimPrefix(lines[0], "        ")
+		if len(lines) > 1 {
+			entry += "\n" + strings.Join(lines[1:], "\n")
+		}
+
+		parts = append(parts, entry)
+	}
+
+	return strings.Join(parts, ",\n"), nil
+}
+
+func replaceReceiveResponseSchema(template string) (string, error) {
+	pathIndex := strings.Index(template, receivePathKey)
+	if pathIndex == -1 {
+		return "", fmt.Errorf("could not find receive path block; run swag init first")
+	}
+	braceOffset := strings.Index(template[pathIndex+len(receivePathKey):], "{")
+	if braceOffset == -1 {
+		return "", fmt.Errorf("could not find opening brace for receive path block")
+	}
+	pathOpenBrace := pathIndex + len(receivePathKey) + braceOffset
+	pathCloseBrace, err := findMatchingBrace(template, pathOpenBrace)
+	if err != nil {
+		return "", err
+	}
+
+	pathBlock := template[pathOpenBrace : pathCloseBrace+1]
+
+	oldSchema := `"schema": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            }
+                        }`
+
+	newSchema := `"schema": {
+                            "$ref": "#/definitions/data.Message"
+                        }`
+
+	updatedPathBlock := strings.Replace(pathBlock, oldSchema, newSchema, 1)
+	if updatedPathBlock == pathBlock {
+		return "", fmt.Errorf("could not replace /v1/receive schema; ensure docs.go is freshly generated by swag")
+	}
+
+	return template[:pathOpenBrace] + updatedPathBlock + template[pathCloseBrace+1:], nil
+}
+
+func findMatchingBrace(input string, openBraceIndex int) (int, error) {
+	depth := 0
+	inString := false
+	escaped := false
+
+	for index := openBraceIndex; index < len(input); index++ {
+		char := input[index]
+
+		if inString {
+			if escaped {
+				escaped = false
+				continue
+			}
+			if char == '\\' {
+				escaped = true
+				continue
+			}
+			if char == '"' {
+				inString = false
+			}
+			continue
+		}
+
+		if char == '"' {
+			inString = true
+			continue
+		}
+
+		switch char {
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return index, nil
+			}
+		}
+	}
+
+	return -1, fmt.Errorf("could not find matching brace")
+}