This library provides an implementation of SHIP 1.0.1 in go, which is part of the EEBUS specification.
Basic understanding of the EEBUS concepts SHIP and SPINE to use this library is required. Please check the corresponding specifications on the EEBUS downloads website.
This repository was started as part of the eebus-go before it was moved into its own repository and this separate go package.
Includes:
- Certificate handling
- mDNS, incl. avahi support (recommended)
- Websocket server and client
- Connection handling, including reconnection and double connections
- Handling of device pairing
- SHIP handshake
- Logging which is also used by spine-go and eebus-go
- Getting Started Guide - Complete guide to integrating ship-go (🚀 10 minute quickstart)
- Security Model - Why
InsecureSkipVerify: trueis correct and secure - Working Examples - 5 complete examples from quickstart to production
- Error Handling - Common errors and solutions
- Production Guide - Complete deployment guide with monitoring and security
- Specification Compliance - 95% SHIP TS 1.0.1 compliance analysis
- Troubleshooting - Systematic debugging approach
- Handshake Guide - 5-phase SHIP handshake with state diagrams
- Connection Lifecycle - Connection states and management
- analysis-docs/ - Comprehensive technical analysis
- README_START_HERE.md - Navigation guide to all analysis documents
- EXECUTIVE_SUMMARY.md - Business-level overview (implementation score: 8.7/10)
- Detailed security model, specification deviations, and improvement roadmap
- Concurrency Guides - Thread safety and deadlock prevention
- Hub Concurrency Guide - Lock ordering and thread safety patterns
- Ship Concurrency Guide - Connection concurrency patterns
- Testing Documentation - Testing guides and utilities
New to ship-go? Start with the Getting Started Guide for a complete walkthrough.
# Build the project
make build
# Run tests with race detection
make test-race
# Run deadlock detection tests
make test-deadlock
# Complete development test cycle
make dev-testExamples:
- Quickstart - Minimal working hub in 5 minutes
- Production - Production-ready hub with monitoring
- Client - Interactive client for connecting to devices
- Pairing - Advanced pairing strategies
# Standard testing
make test # Basic tests
make test-race # Race detection
make test-short # Quick tests only
# Concurrency testing
make test-deadlock # Deadlock detection
make test-deadlock-specific # Core deadlock tests only
make test-stress # High-load stress tests
make test-concurrency # All concurrency tests
# Comprehensive testing
make test-all # All tests
make test-ci # Simulate CI environmentThe library supports a test build tag that reduces timer values for faster test execution:
# Run tests with short timers (120x faster)
go test -tags=test -race ./ship
# Production timers: 60s hello timeout, 10s CMI timeout
# Test timers: 500ms hello timeout, 500ms CMI timeoutSee ship/TEST_BUILD_TAGS.md for detailed documentation on when and how to use test build tags.
# Quick development cycle
make dev-test # Format, lint, and test
# Pre-commit validation
make pre-commit # Complete validation
# Performance monitoring
make benchmark # Run benchmarks
make profile-cpu # Generate CPU profile# Debug deadlocks
make debug-deadlock # Verbose deadlock testing
make test-multicore # Test with different core counts
# Debug race conditions
make debug-race # Multiple test runs
make test-race-verbose # Detailed race output
# Performance debugging
make benchmark-contention # Lock contention analysisThe project includes comprehensive CI/CD testing:
- Standard workflow: Runs on every push/PR with race detection and deadlock tests
- Concurrency workflow: Enhanced testing for concurrency-critical changes
- Nightly monitoring: Continuous validation of thread safety
Local simulation of CI tests:
make test-ci # Run exactly what CI runsThe hub supports configurable connection limits to prevent resource exhaustion:
// Create hub with default limit of 10 connections
hub := hub.NewHub(hubReader, mdns, port, certificate, localService)
// Configure custom connection limit
hub.SetMaxConnections(20) // Allow up to 20 simultaneous connections
// Setting 0 or negative values will use the default of 10
hub.SetMaxConnections(0) // Uses default of 10The connection limit helps protect resource-constrained devices (e.g., Raspberry Pi) from:
- Buggy devices creating excessive connections
- Development mistakes (script loops)
- General resource exhaustion
When the limit is reached:
- Incoming connections receive HTTP 503 (Service Unavailable)
- Outgoing connection attempts return an error
For complete details, see Specification Compliance (95% compliance).
Key deviations from SHIP TS 1.0.1:
- Double connection handling - Uses "connection initiator" logic instead of "most recent" (SHIP 12.2.2)
- PIN Verification - Only supports "none" PIN state (SHIP 13.4.4.3.5.1)
- Access Methods - Basic implementation only (SHIP 13.4.6)
- TLS Fragment Control - Uses standard TLS record sizes (Go crypto/tls limitation)
Supported registration mechanisms (SHIP 5):
- Auto accept (for testing/demos only)
- User verification (recommended for production)
Security Model:
- Uses self-signed certificates with SKI-based device identification
InsecureSkipVerify: trueis correct and secure per SHIP specification- See Security Model for detailed explanation