Skip to content

docs: add bid engine documentation#295

Merged
vertex451 merged 7 commits intomainfrom
luna/documentation-refactoring
Jan 29, 2026
Merged

docs: add bid engine documentation#295
vertex451 merged 7 commits intomainfrom
luna/documentation-refactoring

Conversation

@cloud-j-luna
Copy link
Copy Markdown
Member

@cloud-j-luna cloud-j-luna commented Jun 2, 2025

This PR adds further documentation in to the bid engine codebase and includes consistency improvements in error logging to allow better instrumentation of errors on logging solutions.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Jun 2, 2025

Walkthrough

Added documentation comments to the exported Config struct and standardized logging key names from "err" to "error" across several components; also annotated/expanded private struct fields in bidengine to surface lifecycle, session, cluster, pubsub, and coordination wiring. No behavioral or public API changes.

Changes

Cohort / File(s) Summary
Bid engine: config, order, service
bidengine/config.go, bidengine/order.go, bidengine/service.go
config.go: added descriptive comments above exported Config struct. order.go / service.go: added/annotated many private fields for lifecycle, session, cluster, pubsub, status/order coordination and a provider attr signature service; replaced logging key "err" with "error" in log calls.
Cluster inventory
cluster/inventory.go
Renamed log key "err" to "error" in multiple log statements and removed a trailing blank line in handleRequest. No logic changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I nibble lines where comments grow,
I tweak the logs so errors show.
New notes for structs, small and neat,
The service hums, the orders meet.
A rabbit nods — the code's complete. 🐇✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: adding documentation to the bid engine. The PR includes documentation comments for Config struct and field documentation for order and service structs, directly matching the stated objective.
Description check ✅ Passed The description is directly related to the changeset, mentioning both documentation additions and error logging consistency improvements, which are the primary changes reflected across all modified files.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch luna/documentation-refactoring

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

/bin/bash: line 1: golangci-lint: command not found


Comment @coderabbitai help to get the list of available commands and usage tips.

@cloud-j-luna cloud-j-luna marked this pull request as ready for review June 2, 2025 14:34
@cloud-j-luna cloud-j-luna requested review from boz and troian as code owners June 2, 2025 14:34
Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 04097f4 and c393735.

📒 Files selected for processing (4)
  • bidengine/config.go (1 hunks)
  • bidengine/order.go (11 hunks)
  • bidengine/service.go (4 hunks)
  • cluster/inventory.go (2 hunks)
🧰 Additional context used
🪛 golangci-lint (1.64.8)
bidengine/order.go

35-35: configuraiton is a misspelling of configuration

(misspell)

🪛 GitHub Check: lint
bidengine/order.go

[failure] 35-35:
configuraiton is a misspelling of configuration (misspell)

⏰ Context from checks skipped due to timeout of 90000ms (3)
  • GitHub Check: integration-tests / crd-e2e
  • GitHub Check: release-dry-run
  • GitHub Check: build-bins
🔇 Additional comments (8)
bidengine/config.go (1)

11-12: Excellent documentation improvement!

The added comment clearly explains the purpose and scope of the Config struct, making the code more self-documenting and easier to understand for new developers.

cluster/inventory.go (2)

521-521: Good logging standardization!

Changing the log key from "err" to "error" improves consistency and makes logs more readable for monitoring and debugging tools.


689-689: Consistent logging improvement!

The standardization of error logging keys enhances log consistency across the codebase.

bidengine/order.go (3)

30-61: Outstanding documentation enhancement!

The detailed comments for each struct field significantly improve code readability and maintainability. This makes it much easier for developers to understand the purpose and lifecycle of each component.

🧰 Tools
🪛 golangci-lint (1.64.8)

35-35: configuraiton is a misspelling of configuration

(misspell)

🪛 GitHub Check: lint

[failure] 35-35:
configuraiton is a misspelling of configuration (misspell)


176-191: Excellent channel documentation!

The detailed comments explaining the purpose of each channel variable greatly enhance code clarity and make the complex async logic much easier to follow.


236-236: Consistent logging key standardization!

The systematic change from "err" to "error" in log messages improves consistency across the codebase and enhances log readability for monitoring and debugging tools.

Also applies to: 334-334, 350-350, 373-373, 409-409, 440-440, 475-475, 491-491, 583-583

bidengine/service.go (2)

107-139: Comprehensive service documentation!

The detailed comments for the service struct fields provide excellent clarity on the purpose and relationships between components. This significantly improves code maintainability and developer onboarding.


264-264: Consistent logging standardization!

The change from "err" to "error" in logging keys maintains consistency with the logging improvements across the entire codebase.

Also applies to: 273-273, 295-295

@chainzero
Copy link
Copy Markdown

@cloud-j-luna - struct field comments and standardization on "error" make sense and LGTM.

@troian - as it pertains to comment standardization - again all looks good from my perspective. Any concerns on commenting style/content form your perspective?

zach-source pushed a commit to zach-source/provider that referenced this pull request Jul 29, 2025
…ssues (akash-network#295)

This commit addresses two related issues that prevented proper deployment
and access to services using shared memory (SHM) volumes and caused
lease-shell to fail when attempting to access StatefulSet workloads.

## Problem Analysis

1. **SHM Volume Mount Naming Mismatch**: Services with SHM storage failed
   to deploy with error "volumeMounts[0].name: Not found: 'test-shm'".
   The issue was inconsistent naming between volume creation and volume
   mount creation in the workload builder.

2. **Incorrect StatefulSet Detection**: The lease-shell feature failed
   with "statefulsets.apps 'test' not found" because ServiceStatus()
   incorrectly determined workload type by checking if any storage
   parameter had a mount path, rather than checking for persistent storage.

## Root Cause

### Volume Naming Issue
- Volume mounts used: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes used: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- For SHM volumes, `params.Name` and `storage.Name` could differ

### StatefulSet Detection Issue
- ServiceStatus() checked `param.Mount \!= ""` to determine StatefulSet
- Deploy() checked `storage.Attributes.Find(sdl.StorageAttributePersistent)`
- This mismatch caused ServiceStatus to look for wrong workload type

## Solution

### Volume Mount Fix
- Ensured both volume mounts and volumes use consistent naming
- Volume mounts: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- PVC names: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`

### StatefulSet Detection Fix
- Updated ServiceStatus() to use same logic as Deploy()
- Changed from checking `param.Mount \!= ""`
- To checking `storage.Attributes.Find(sdl.StorageAttributePersistent).AsBool()`
- Added comprehensive comment explaining the requirement for consistency

## Testing

Verified fix resolves both issues:
- SHM volumes mount successfully without naming conflicts
- lease-shell correctly identifies and connects to StatefulSet workloads
- Deployment type detection matches between ServiceStatus and Deploy

Resolves: akash-network#295
zach-source added a commit to zach-source/provider that referenced this pull request Jul 29, 2025
…ssues (akash-network#295)

This commit addresses two related issues that prevented proper deployment
and access to services using shared memory (SHM) volumes and caused
lease-shell to fail when attempting to access StatefulSet workloads.

## Problem Analysis

1. **SHM Volume Mount Naming Mismatch**: Services with SHM storage failed
   to deploy with error "volumeMounts[0].name: Not found: 'test-shm'".
   The issue was inconsistent naming between volume creation and volume
   mount creation in the workload builder.

2. **Incorrect StatefulSet Detection**: The lease-shell feature failed
   with "statefulsets.apps 'test' not found" because ServiceStatus()
   incorrectly determined workload type by checking if any storage
   parameter had a mount path, rather than checking for persistent storage.

## Root Cause

### Volume Naming Issue
- Volume mounts used: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes used: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- For SHM volumes, `params.Name` and `storage.Name` could differ

### StatefulSet Detection Issue
- ServiceStatus() checked `param.Mount \!= ""` to determine StatefulSet
- Deploy() checked `storage.Attributes.Find(sdl.StorageAttributePersistent)`
- This mismatch caused ServiceStatus to look for wrong workload type

## Solution

### Volume Mount Fix
- Ensured both volume mounts and volumes use consistent naming
- Volume mounts: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- PVC names: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`

### StatefulSet Detection Fix
- Updated ServiceStatus() to use same logic as Deploy()
- Changed from checking `param.Mount \!= ""`
- To checking `storage.Attributes.Find(sdl.StorageAttributePersistent).AsBool()`
- Added comprehensive comment explaining the requirement for consistency

## Testing

Verified fix resolves both issues:
- SHM volumes mount successfully without naming conflicts
- lease-shell correctly identifies and connects to StatefulSet workloads
- Deployment type detection matches between ServiceStatus and Deploy

Resolves: akash-network#295
zach-source added a commit to zach-source/provider that referenced this pull request Jul 29, 2025
…ssues (akash-network#295)

This commit addresses two related issues that prevented proper deployment
and access to services using shared memory (SHM) volumes and caused
lease-shell to fail when attempting to access StatefulSet workloads.

## Problem Analysis

1. **SHM Volume Mount Naming Mismatch**: Services with SHM storage failed
   to deploy with error "volumeMounts[0].name: Not found: 'test-shm'".
   The issue was inconsistent naming between volume creation and volume
   mount creation in the workload builder.

2. **Incorrect StatefulSet Detection**: The lease-shell feature failed
   with "statefulsets.apps 'test' not found" because ServiceStatus()
   incorrectly determined workload type by checking if any storage
   parameter had a mount path, rather than checking for persistent storage.

## Root Cause

### Volume Naming Issue
- Volume mounts used: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes used: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- For SHM volumes, `params.Name` and `storage.Name` could differ

### StatefulSet Detection Issue
- ServiceStatus() checked `param.Mount \!= ""` to determine StatefulSet
- Deploy() checked `storage.Attributes.Find(sdl.StorageAttributePersistent)`
- This mismatch caused ServiceStatus to look for wrong workload type

## Solution

### Volume Mount Fix
- Ensured both volume mounts and volumes use consistent naming
- Volume mounts: `fmt.Sprintf("%s-%s", service.Name, params.Name)`
- Volumes: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`
- PVC names: `fmt.Sprintf("%s-%s", service.Name, storage.Name)`

### StatefulSet Detection Fix
- Updated ServiceStatus() to use same logic as Deploy()
- Changed from checking `param.Mount \!= ""`
- To checking `storage.Attributes.Find(sdl.StorageAttributePersistent).AsBool()`
- Added comprehensive comment explaining the requirement for consistency

## Testing

Verified fix resolves both issues:
- SHM volumes mount successfully without naming conflicts
- lease-shell correctly identifies and connects to StatefulSet workloads
- Deployment type detection matches between ServiceStatus and Deploy

Resolves: akash-network#295
zach-source added a commit to zach-source/provider that referenced this pull request Jul 29, 2025
akash-network#295)

This commit addresses two critical issues in the Akash provider:

1. StatefulSet Detection Fix:
   - Fixed incorrect logic in ServiceStatus that was checking for any mounted
     storage instead of persistent storage to determine workload type
   - The bug caused services with RAM volumes to incorrectly attempt StatefulSet
     operations, resulting in "statefulsets.apps not found" errors
   - Now correctly checks storage.Attributes.Find(sdl.StorageAttributePersistent)
     to match the deployment creation logic

2. WebSocket Error Handling in lease-shell:
   - Fixed improper error handling when ServiceStatus fails during shell operations
   - Previously used http.Error() on WebSocket connections, causing protocol violations
   - Now properly uses WebSocket writer with LeaseShellCodeFailure and logs errors
   - Prevents silent failures and improves debugging for shell access issues

Added comprehensive unit tests for StatefulSet detection logic covering:
- Services with persistent storage (should use StatefulSet)
- Services with non-persistent storage (should use Deployment)
- Services with no storage (should use Deployment)

These fixes ensure proper workload type detection and improve error visibility
for lease-shell operations, resolving issues with shell access to deployments
using RAM volumes.
zach-source added a commit to zach-source/provider that referenced this pull request Jul 30, 2025
akash-network#295)

This commit addresses two critical issues in the Akash provider:

1. StatefulSet Detection Fix:
   - Fixed incorrect logic in ServiceStatus that was checking for any mounted
     storage instead of persistent storage to determine workload type
   - The bug caused services with RAM volumes to incorrectly attempt StatefulSet
     operations, resulting in "statefulsets.apps not found" errors
   - Now correctly checks storage.Attributes.Find(sdl.StorageAttributePersistent)
     to match the deployment creation logic

2. WebSocket Error Handling in lease-shell:
   - Fixed improper error handling when ServiceStatus fails during shell operations
   - Previously used http.Error() on WebSocket connections, causing protocol violations
   - Now properly uses WebSocket writer with LeaseShellCodeFailure and logs errors
   - Prevents silent failures and improves debugging for shell access issues

Added comprehensive unit tests for StatefulSet detection logic covering:
- Services with persistent storage (should use StatefulSet)
- Services with non-persistent storage (should use Deployment)
- Services with no storage (should use Deployment)

These fixes ensure proper workload type detection and improve error visibility
for lease-shell operations, resolving issues with shell access to deployments
using RAM volumes.
@vertex451 vertex451 requested a review from a team as a code owner January 29, 2026 15:36
@vertex451 vertex451 merged commit f136e98 into main Jan 29, 2026
12 checks passed
@vertex451 vertex451 deleted the luna/documentation-refactoring branch January 29, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants