Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
521 lines (380 loc) · 11.9 KB

MIGRATION_GUIDE.md

File metadata and controls

521 lines (380 loc) · 11.9 KB
Raw

Migration Guide: Debug and Trace Export Improvements

This guide helps existing Glassbox users adapt to the enhanced validation and error handling in the debug command and trace export functionality.

Summary of Changes

What's New

  • ✅ More detailed error messages with remediation guidance
  • ✅ Additional validation checks in dry-run mode
  • ✅ Comprehensive trace export validation
  • ✅ Security improvements (path traversal, null byte detection)
  • ✅ Better multi-error reporting

What's the Same

  • ✅ All existing CLI flags work exactly as before
  • ✅ All existing commands produce the same output (with better errors)
  • ✅ No breaking API changes
  • ✅ Backward compatible with all scripts

For Users

No Action Required

Your existing commands will work exactly as before. The changes only enhance error messages and add validation checks.

Example: This command works identically:

glassbox debug --network testnet <tx-hash>

What You'll Notice

  1. Better Error Messages

    • Errors now include "Fix:" sections with clear remediation
    • Examples show correct usage
    • Multiple errors reported at once

  2. Earlier Failure Detection

    • Invalid configurations caught before network/simulator operations
    • Dry-run mode checks more conditions

  3. More Security

    • Path traversal attempts blocked
    • Invalid URLs rejected early

Recommended Actions

  1. Try Dry-Run Mode

    glassbox debug --dry-run --network testnet <tx-hash>

    This now performs 9 comprehensive checks (previously 5).

  2. Review Error Messages If you encounter errors, read the "Fix:" section for guidance.

  3. Update CI/CD Scripts Consider adding dry-run validation before expensive operations:

    # Add this before your actual debug command
glassbox debug --dry-run --network $NETWORK $TX_HASH || exit 1

For Developers

Breaking Changes

None. All changes are additive and backward compatible.

API Changes

New Functions (Safe to Use)

Debug Command Validation:

// These are new helper functions, safe to call
validateRPCURL(rawURL string) error
validateSimulatorVersion(version string) error  
validateProtocolVersion(version uint32) error

Trace Export Validation:

// New comprehensive validation functions
ValidateTraceExportParams(trace *ExecutionTrace, format, outputPath string, opts ExportOptions) error
ValidateTraceFormatCompatibility(trace *ExecutionTrace, format string) error

Enhanced Functions (Compatible)

These functions now perform additional validation but remain compatible:

// Enhanced but compatible
runDebugDryRun(cmd *cobra.Command, txHash string) error
ValidateTraceInputs(verbosity, exportFormat, eventFilter, outputPath string) error
ExportExecutionTraceWithOptions(trace *ExecutionTrace, format string, outputPath string, opts ExportOptions) error

Error Handling Changes

Before:

err := ValidateTraceInputs(verbosity, format, filter, path)
// Generic error messages

After:

err := ValidateTraceInputs(verbosity, format, filter, path)
// Now returns detailed *TraceInputError with Fix: sections
// Still compatible - check err != nil as before

Testing Changes

No changes required to existing tests.

New test files added:

  • internal/cmd/debug_dry_run_test.go
  • internal/trace/validate_test.go

These don't affect existing tests.

For CI/CD Pipelines

Recommended Updates

1. Add Dry-Run Validation Step

Before:

- name: Debug Transaction
  run: glassbox debug --network testnet $TX_HASH

After:

- name: Validate Configuration
  run: glassbox debug --dry-run --network testnet $TX_HASH

- name: Debug Transaction
  run: glassbox debug --network testnet $TX_HASH

Benefit: Catches config errors faster, before expensive network operations.

2. Capture Enhanced Error Output

Before:

- name: Debug
  run: glassbox debug --network testnet $TX_HASH
  continue-on-error: true

After:

- name: Debug
  run: |
    glassbox debug --network testnet $TX_HASH 2>&1 | tee debug.log
  continue-on-error: true

- name: Upload Logs
  if: failure()
  uses: actions/upload-artifact@v3
  with:
    name: debug-logs
    path: debug.log

Benefit: Enhanced error messages with Fix: sections are now captured for debugging.

3. Use Trace Export Validation

Before:

- name: Export Trace
  run: |
    glassbox debug --trace-output ./trace.html --network testnet $TX_HASH

After:

- name: Export Trace
  run: |
    # Validation happens automatically
    glassbox debug --trace-output ./artifacts/trace.html --format html --network testnet $TX_HASH

- name: Upload Trace
  uses: actions/upload-artifact@v3
  with:
    name: execution-trace
    path: artifacts/trace.html

Benefit: Export validation is now automatic with detailed error messages.

For Script Authors

Enhanced Error Handling

Before:

#!/bin/bash
if ! glassbox debug --network testnet $TX_HASH; then
  echo "Debug failed"
  exit 1
fi

After:

#!/bin/bash
# Dry-run validation first
if ! glassbox debug --dry-run --network testnet $TX_HASH; then
  echo "Configuration validation failed - see errors above"
  exit 1
fi

# Actual execution
if ! glassbox debug --network testnet $TX_HASH; then
  echo "Debug execution failed - see errors above"
  exit 1
fi

Benefit: Failures are caught earlier with better diagnostics.

Path Security

Before:

# Potentially unsafe
OUTPUT="../../../somewhere/$TX_HASH.html"
glassbox debug --trace-output $OUTPUT --network testnet $TX_HASH

After:

# Safer - validation will catch traversal
OUTPUT="./traces/$TX_HASH.html"
glassbox debug --trace-output $OUTPUT --network testnet $TX_HASH

# Or use absolute paths
OUTPUT="$(pwd)/traces/$TX_HASH.html"
glassbox debug --trace-output $OUTPUT --network testnet $TX_HASH

Benefit: Path traversal attempts are now detected and blocked.

For Docker Users

No Changes Required

The Docker container works exactly as before:

FROM golang:1.21

WORKDIR /app
COPY . .
RUN go build -o glassbox ./cmd/glassbox

# Same usage as before
ENTRYPOINT ["./glassbox"]
CMD ["debug", "--help"]

Recommended: Add Healthcheck

# Add this to validate the environment
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD glassbox debug --dry-run --network testnet <known-tx-hash> || exit 1

Common Migration Scenarios

Scenario 1: Existing Shell Scripts

What to do: No changes required, but consider adding --dry-run for validation.

Example:

# Your existing script
./my-debug-script.sh <tx-hash>

# Enhanced version
#!/bin/bash
# my-debug-script.sh
TX_HASH=$1

# Add validation step (optional but recommended)
echo "Validating configuration..."
if ! glassbox debug --dry-run --network testnet $TX_HASH; then
  echo "Validation failed"
  exit 1
fi

# Your existing command
glassbox debug --network testnet $TX_HASH

Scenario 2: CI/CD Integration

What to do: Add validation step before expensive operations.

Example (GitHub Actions):

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      # New: Add validation step
      - name: Validate Config
        run: |
          glassbox debug --dry-run \
            --network testnet \
            --trace-output ./trace.html \
            ${{ env.TX_HASH }}
      
      # Existing: Run debug
      - name: Debug Transaction
        run: |
          glassbox debug \
            --network testnet \
            --trace-output ./trace.html \
            ${{ env.TX_HASH }}

Scenario 3: Automated Testing

What to do: No changes required. Tests work as before.

Example:

# Your existing test
test_debug() {
  TX_HASH="abc123..."
  glassbox debug --network testnet $TX_HASH
  assert_success
}

# Still works - no changes needed

Scenario 4: Error Parsing Scripts

What to do: Update regex patterns if you parse errors.

Before:

# Old error format
ERROR=$(glassbox debug ... 2>&1 | grep "FAIL")

After:

# Enhanced error format includes Fix: sections
ERROR=$(glassbox debug ... 2>&1 | grep -A 3 "FAIL")
# Now captures error + Fix: section

Troubleshooting

"I'm getting new errors I didn't see before"

This is expected. The enhanced validation catches issues earlier.

Action: Read the "Fix:" section in the error message for remediation.

"My CI pipeline is now failing"

Cause: Validation caught a pre-existing configuration issue.

Action:

  1. Read the error message for specific issue
  2. Follow the "Fix:" guidance
  3. Test locally with --dry-run first

"I don't want the extra validation"

Option 1 (Recommended): Fix the underlying issues - validation prevents runtime failures.

Option 2: The validation only runs in PreRunE and during export. Core functionality is unchanged.

"Errors are too verbose"

This is intentional - verbose errors help debugging.

Action:

  • Errors include all necessary information to fix issues
  • Multiple errors are reported together to fix in one pass
  • Use --dry-run to validate without execution

Rollback Instructions

If you need to revert to previous behavior:

Option 1: Use Previous Git Tag

git checkout <previous-tag>
go build -o glassbox ./cmd/glassbox

Option 2: Conditional Branch

if glassbox version | grep -q "new-version"; then
  # Use new validation
  glassbox debug --dry-run ...
else
  # Old version
  glassbox debug ...
fi

Option 3: Pin Version

# In go.mod
require github.com/dotandev/glassbox v1.2.3  // pin to old version

Note: Rollback should not be necessary - all changes are backward compatible.

FAQ

Q: Do I need to update my code?

A: No. All changes are backward compatible.

Q: Will my scripts break?

A: No. Existing commands work exactly as before.

Q: Why more validation?

A: To catch errors earlier with better diagnostics, saving time debugging.

Q: Are there performance impacts?

A: Negligible. Validation adds <10ms and prevents expensive failed operations.

Q: What if I find a bug?

A: Report it with the error message and command used. The enhanced errors will help debug faster.

Q: Can I disable validation?

A: Validation is always enabled to ensure safety and security. Focus on fixing the underlying issues.

Support and Resources

Documentation

  • Debug Command: docs/debug-command.md
  • Trace Export: docs/trace-export-validation.md
  • Changes: CHANGES_QUICK_REFERENCE.md
  • Implementation: IMPLEMENTATION_SUMMARY.md

Commands

# Get help
glassbox debug --help

# Validate configuration
glassbox debug --dry-run --network testnet <tx-hash>

# Check environment
glassbox doctor

# View version
glassbox version

Reporting Issues

Include in your bug report:

  1. Full command used
  2. Complete error output (now includes Fix: sections)
  3. Glassbox version: glassbox version
  4. Operating system

Timeline

  • Now: Changes available in this PR/branch
  • Testing: Run test suite, try examples
  • Merge: After review and testing
  • Release: Included in next release

Conclusion

No migration work required - everything is backward compatible. The enhancements provide better error messages, more security, and improved diagnostics without breaking existing functionality.

Recommended Actions:

  1. ✅ Read error messages when they occur (now includes Fix: sections)
  2. ✅ Consider adding --dry-run to CI/CD pipelines
  3. ✅ Update error parsing scripts if you parse error output
  4. ✅ Test the changes with your existing workflows

Questions? Check the documentation or report issues with the enhanced error output for faster resolution.