Identify differences to latest OSBAPI 2.17 spec and document missing features

[Copilot]

This PR addresses issue #X by providing a comprehensive analysis of the gaps between the current openbrokerapi implementation (supporting OSBAPI 2.13+) and the latest Open Service Broker API 2.17 specification.

Analysis Summary

The current implementation supports OSBAPI 2.13+ as the minimum version but is missing several key features introduced in 2.17. This analysis identifies 13 major feature categories that are not yet implemented:

Critical Missing Features

Service Binding Rotation - A major new capability in 2.17 that allows credentials to be rotated seamlessly:

• ServicePlan.binding_rotatable field to declare rotation support
• BindDetails.predecessor_binding_id for creating successor bindings
• BindingMetadata with expiration timing (expires_at, renew_before)

Maintenance Info Object - Comprehensive maintenance operation support:

• MaintenanceInfo class with version and description
• Integration across provision, update, and service plan definitions
• MaintenanceInfoConflict error code for version mismatches

Service Instance Metadata - Enhanced metadata support:

• ServiceInstanceMetadata with labels and attributes
• Integration in provision, update, and fetch responses

Network Endpoints - Service connectivity information:

• Endpoint class defining host, ports, and protocol
• Integration in binding responses to inform network configuration

Additional Enhancements

• Service.allow_context_updates for context change support
• ServicePlan.maximum_polling_duration for per-plan polling limits
• Retry-After header support in last operation responses
• Enhanced error handling capabilities

Files Added

• OSBAPI_2_17_ANALYSIS.md - Detailed technical analysis with implementation requirements
• MISSING_FEATURES_SNIPPETS.md - Ready-to-use code snippets for implementing each missing feature
• Updated TODO.md - Cross-referenced existing TODO items with new findings

Implementation Notes

All identified missing features are backwards compatible additions that can be implemented incrementally without breaking existing broker implementations. The analysis provides exact code locations and implementation patterns to facilitate future development.

This work establishes a clear roadmap for bringing the library up to full OSBAPI 2.17 compliance while maintaining compatibility with existing 2.13+ brokers.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Identify differences to latest spec version</issue_title>
<issue_description>Open Service Broker API updated their spec and released 2.17.

Verify which changes are not covered or only partially covered by the implementation.

Write markdown snippets for missing features.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #483

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.