RDKEMW-18322: Onboard common-utilities repository to OpenSpec SDD - #99
Merged
Conversation
Reason For change: Onboard open-spec Signed-off-by: satya200 <tinkusahu.com@gmail.com>
Contributor
Contributor
There was a problem hiding this comment.
Pull request overview
This PR onboards the common_utilities repository to OpenSpec by adding a baseline architecture documentation set (subsystem deep-dives, runtime flows, diagrams, and an index) plus OpenSpec workflow skill/prompt assets under .github/.
Changes:
- Adds an
openspec/documentation tree: project overview, subsystem API analyses, runtime sequence/state diagrams, and an index. - Adds Mermaid-based architecture diagrams for module interactions and dependencies.
- Adds OpenSpec configuration and GitHub “opsx” skills/prompts to support proposal/apply/sync/archive workflows.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
openspec/subsystems/utils.md |
Documents device/system utilities API surface and behavior (contains several API name/return-code mismatches vs headers). |
openspec/subsystems/uploadutils.md |
Documents upload library API and flows (currently references multiple non-existent or misnamed APIs). |
openspec/subsystems/parsejson.md |
Documents JSON parsing library interface and usage patterns. |
openspec/subsystems/dwnlutils.md |
Documents download library API and behavior (notably, doInteruptDwnl() return semantics need alignment). |
openspec/runtime/upload_flows.md |
Mermaid runtime flows for upload operations (currently uses outdated API names/parameters). |
openspec/runtime/download_flows.md |
Mermaid runtime flows for download operations. |
openspec/project.md |
High-level architecture baseline tying modules together (includes outdated upload API usage example). |
openspec/INDEX.md |
Navigation index into the OpenSpec documentation set. |
openspec/diagrams/module_interactions.md |
Visual diagrams for architecture, layering, thread-safety, and build variants. |
openspec/config.yaml |
OpenSpec config enabling the spec-driven schema. |
.github/skills/openspec-sync-specs/SKILL.md |
Skill definition for syncing delta specs into main specs. |
.github/skills/openspec-propose/SKILL.md |
Skill definition for generating proposal/design/tasks artifacts. |
.github/skills/openspec-onboard/SKILL.md |
Guided onboarding workflow skill. |
.github/skills/openspec-explore/SKILL.md |
Explore-mode skill guidance. |
.github/skills/openspec-archive-change/SKILL.md |
Skill definition for archiving a change. |
.github/skills/openspec-apply-change/SKILL.md |
Skill definition for applying/implementing tasks from a change. |
.github/prompts/opsx-sync.prompt.md |
Prompt for syncing delta specs. |
.github/prompts/opsx-propose.prompt.md |
Prompt for proposing a change and generating artifacts. |
.github/prompts/opsx-onboard.prompt.md |
Prompt for guided onboarding workflow. |
.github/prompts/opsx-explore.prompt.md |
Prompt for explore mode. |
.github/prompts/opsx-archive.prompt.md |
Prompt for archiving a change. |
.github/prompts/opsx-apply.prompt.md |
Prompt for applying/implementing a change. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+76
to
+87
| int performMetadataPost( | ||
| void *curl, // Curl context | ||
| const char *endpoint, // Backend metadata service URL | ||
| FileUpload_t *upload_spec, // Upload configuration | ||
| char *output_file // Path to save response (S3 URLs) | ||
| ); | ||
| // Stage 1: Submit file metadata to backend service | ||
| // Backend returns S3 pre-signed URLs in response | ||
| // Usage: Obtain S3 upload credentials from CodeBig or backend | ||
| // Returns: 0 success, -1 failure | ||
| // Output: Writes S3 pre-signed URLs to output_file | ||
|
|
Comment on lines
+109
to
+112
| // Reads first line, strips trailing newline | ||
| // Returns: 0 success, -1 failure | ||
| // Usage: Extract URL from performMetadataPost() output file | ||
| ``` |
Comment on lines
+117
to
+135
| int performCodebigUpload( | ||
| const char *device_id, // Device identifier | ||
| const char *local_file, // File to upload | ||
| const char *backend_url, // CodeBig service endpoint | ||
| MtlsAuth_t *auth // mTLS credentials | ||
| ); | ||
| // Integrated CodeBig upload (metadata + S3 in one call) | ||
| // Internally handles two-stage workflow | ||
| // Returns: 0 success, -1 failure | ||
| // Usage: High-level upload with CodeBig orchestration | ||
|
|
||
| int getCodebigCredentials( | ||
| char *out_endpoint, // Output: CodeBig service URL | ||
| size_t endpoint_sz, | ||
| char *out_service_type // Output: Service type identifier | ||
| ); | ||
| // Query CodeBig service endpoint | ||
| // Reads from RFC or configuration | ||
| // Returns: 0 success, -1 failure |
Comment on lines
+141
to
+154
| int getMtlsCertificate( | ||
| MtlsAuth_t *out_auth // Output: Certificate structure | ||
| ); | ||
| // Obtain current mTLS certificate via rdkcertselector | ||
| // Handles certificate rotation and fallback | ||
| // Returns: MTLS_CERT_FETCH_SUCCESS (0), MTLS_CERT_FETCH_FAILURE (-1) | ||
| // Usage: Called automatically by performMetadataPost() if enabled | ||
|
|
||
| int rotateMtlsCertificate(void); | ||
| // Trigger certificate rotation cycle | ||
| // Requests new certificate from rdkcertselector | ||
| // Returns: 0 success, -1 failure | ||
| // Usage: After certificate expiration or explicit request | ||
| ``` |
Comment on lines
+159
to
+173
| int getUploadStatus( | ||
| const char *status_file // Path to status file | ||
| ); | ||
| // Query upload operation result | ||
| // Reads persistent state file | ||
| // Returns: UPLOAD_SUCCESS (0), UPLOAD_FAIL (-1) | ||
|
|
||
| void setUploadStatus( | ||
| long http_code, // HTTP response code | ||
| int curl_code // libcurl error code | ||
| ); | ||
| // Record upload operation result (internal) | ||
| // Persists status for diagnostics | ||
| // Invoked automatically by upload functions | ||
| ``` |
Comment on lines
+323
to
+335
| // Stage 1: POST metadata to backend | ||
| FileUpload_t metadata = {...}; // Configure POST payload | ||
| int http_code = 0; | ||
| int result = performMetadataPost( | ||
| curl, | ||
| metadata, | ||
| "s3_urls.txt" // Output file with pre-signed URLs | ||
| ); | ||
|
|
||
| // Stage 2: PUT to S3 | ||
| char s3_url[512]; | ||
| extractS3PresignedUrl("s3_urls.txt", s3_url, sizeof(s3_url)); | ||
| result = performS3PutUpload(s3_url, "/local/file.bin", &mtls_auth); |
Comment on lines
+29
to
+33
| int getDeviceProperties(DeviceProperty_t *pDevice_info); | ||
| // Retrieve all device properties in one call | ||
| // Reads from /etc/device.properties (or /tmp in test mode) | ||
| // Returns: UTILS_SUCCESS (1), UTILS_FAILURE (-1) | ||
| // Output: Populates DeviceProperty_t structure |
Comment on lines
+73
to
+87
| size_t GetDeviceType(char *pDeviceType, size_t szBufSize); | ||
| // Get device type identifier | ||
| // Returns: Length of type string | ||
| // Example: "mediaclient" or "broadband" | ||
|
|
||
| size_t GetVersionNum(char *pVersionNum, size_t szBufSize); | ||
| // Get firmware version string | ||
| // Returns: Length of version string | ||
| // Example: "CGM4331MU-20231201" | ||
|
|
||
| int GetImageDetails(ImageDetails_t *pImageDetails); | ||
| // Get image metadata structure | ||
| // Returns: UTILS_SUCCESS (1), UTILS_FAILURE (-1) | ||
| // Output: Populates ImageDetails_t with current_img_name | ||
|
|
Comment on lines
+125
to
+127
| int getImageUpdateFrequency(void); | ||
| // Get recommended update frequency | ||
| // Returns: Frequency in days, 0 if not specified |
Comment on lines
+133
to
+140
| int cmdExec( | ||
| const char *cmd, // Linux shell command to execute | ||
| char *output, // Output buffer for command results | ||
| unsigned int size_buff // Buffer size (max 4096) | ||
| ); | ||
| // Execute arbitrary Linux command and capture output | ||
| // Returns: UTILS_SUCCESS (0), UTILS_FAILURE (-1) | ||
| // Output: Command stdout in output buffer |
Contributor
|
b'## WARNING: A Blackduck scan failure has been waived A prior failure has been upvoted
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reason For change: Onboard open-spec