OpenStack-SDK-PHP/TechnicalRequirements

Requirements

Top-level objectives

Ease of installation

• Composer/Packagist package (Priority 1)
• PHAR file (Priority 2)

PEAR and Linux packages are not currently part of the requirements. If someone believes one of them should be handled please file a blueprint and make a case.

Ease of use

• Human-readable service names: minimize usage of OpenStack codenames
• Well-written and highly accessible end-user documentation that strives to be as comprehensive and helpful as possible
  • Assumption-free documention, capable of expressing a concept soundly to both novices and experts
  • Quick start guides for every service, starting with most popular ones
  • Consistent use of code samples [Discussion point: could we store these as sample files in GitHub or as gists and then include them from within the documentation?]
  • API documentation
  • PHP docblock annotations
• A simple API that minimizes complexity and vendor differences
• Multiple forums to make announcements and answer queries:
  • GitHub issues
  • IRC
  • -users@ mailing list [Discussion point: should this be different from the contributors mailing list (see section on contributing below)?]
  • Twitter account (similar to https://twitter.com/awsforphp)

Ease of contributing

• Community-driven decisions with full feedback and transparency
• A CONTRIBUTING guide, encouraging all forms of engagement
• Active on irc channels
• A mailing list
• Google Hangout meetings

Technical requirements

HTTP transport layer

• Support for all HTTP request methods, including custom ones
• Requests, responses, headers and URLs can be easily accessed and editable (i.e. they serve as objects)
• Persistent connections
• Connection pooling
• Parallelization with multi-cURL
• Request bodies are handled as streams rather than strings - to avoid in-memory storage
  • Ability to register a Swift stream wrapper, so that native filesystem functions can be utilized
  • Perhaps the ability to use `swift://` protocol
• Flexible authentication
• Auth caching
• Multiple connection types offered through adapters: cURL, sockets, test/mock
• Redirect handling
• SSL support
• Retry strategies (in response to cURL/HTTP errors, throttling, etc.)

Service layer

General

• Support for multiple service versions, easily selected by an end-user

• The core library will contain common functionality essential to the running of a pure OpenStack installation

Extensions

• Extensions, whether vendor-specific or not, need to be handled appropriately. There is a strong argument for extracting this supplementary functionality from the core library and placing it in other namespaces (or repositories)

• Discussion point: Need to agree where to place / how to structure vendor extensions

Service clients

• Discussion point: Need to agree whether each service will act as its own client, or whether a more global context will be used.

• Discussion point: Need to agree the best way to define API services (json-schema, Guzzle DSL, userland code)

• Discussion point: Need to agree the best way to create or marshall service objects from their descriptions - i.e. some form of service container

API concepts

• We should objectify and properly abstract the basic concepts of a ReSTful API. For example: a service is composed of Resources
  • Each resource has state and is expressed through properties.
    • Discussion point: How strict should we be with API resource properties?
  • Each resource can be modified with ReSTful operations. Each operation is composed of the following:
    • A HTTP method
    • A URL (absolute or relative)
    • Parameters (key/val array)
    • A description
    • A definition of how its response will be parsed

Miscellaneous

Events

• We should use Event dispatching to expose all moments of a request's lifecycle to the end-user. This allows them to add in or modify functionality as it suits them, rather than them having to extend and override main classes.
• We should think about what "events" are most important for an end-user: request.before_send, request.sent, request.error, curl.progress, etc.

Iterators

• We should support iterators and request-based append functionality.
• We should make this as consistent as possible and hide any underlying inconsistencies.
• We should also utilize native SPL iterators where possible.

Waiters

• Ability for users to "wait for" an operation to achieve some state. For example, a user may want to wait until a Nova instance has finished building before continuing with their script.
• This should be easy for an end-user to work with

Error handling

• Error messages need to be as descriptive and helpful as possible. We should not expose them to an API message or HTTP status code.

• Discussion point: Need to agree about how to use exception classes

Workflow/methodology

Standardisation

• PSR-2 coding style
• PSR-3 logging interface
• PSR-4 autoloading

Documentation

Discussion point: Need to discuss what technology or tooling we will use to write our end-user documentation - i.e. Sphinx, markup Discussion point: Need to decide how to host our documentation - i.e. Read the Docs or OpenStack domain

Testing

Methodology

Discussion point: Need to decide our testing methodology.

Tooling

Discussion point: Need to decide our testing tool.

Continuous integration

• Travis?

OpenStack has its own continuous integration framework, but we can probably use Travis in addition to that.