2017 © Pedro Peláez
 

library http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

image

simplecomplex/http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  • Monday, June 25, 2018
  • by jacobfriis
  • Repository
  • 2 Watchers
  • 0 Stars
  • 79 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 18 Versions
  • 108 % Grown

The README.md

Http

High-level HTTP client and (Slim) service utility.
Client provides response validation and mocking.
Service provides standardized and predictable responses., (*1)

, (*2)

▹ Client

, (*3)

Request options

The HttpClient->request() method accepts it's own options
as well as options for the underlying RestMini Client., (*4)

Own options
  • (bool) debug_dump: log request and response
  • (bool|arr) cacheable: cache response/load response from cache
  • (bool|arr) validate_response: validate the response body against a validation rule set
  • (bool|arr) mock_response: don't send the request, return predefined mock response
  • (int) retry_on_unavailable: millisecs; try again later upon
    503 Service Unavailable|host not found|connection failed
  • (arr) require_response_headers: list of response header keys required
  • (bool) err_on_endpoint_not_found: err on 404 + HTML response
  • (bool) err_on_resource_not_found: err on 204 or 404 + JSON response
  • (arr) log_warning_on_status: key is status code, value is true
Options processing

Apart from options passed directly to HttpClient->request()
there may also exist settings (see Config) for the: - provider: the service host - service: a group of endpoints - endpoint: the actual endpoint - method: literal HTTP method or an alias (like GET aliases index and retrieve), (*5)

During request preparations settings and options get merged, so that
options override method settings, which override endpoint settings, which override... (you get it).
Sounds like a lot of work, but it isn't really., (*6)

, (*7)

#### ▹▹ Client CLI commands #### , (*8)

(remote) Service configuration
# Show provider settings.
php cli.php config-get -a global http-provider.prvdr

# Show service settings.
php cli.php config-get -a global http-service.prvdr.example-service

# Show endpoint settings.
php cli.php config-get -a global http-endpoint.prvdr.example-service.ndpnt

# Show method settings.
php cli.php config-get -a global http-method.prvdr.example-service.ndpnt.GET
Validation rule sets
# Show cached validation rule set.
php cli.php cache-get http-response_validation-rule-set prvdr.example-service.ndpnt.GET

# Delete cached validation rule set.
php cli.php cache-delete http-response_validation-rule-set prvdr.example-service.ndpnt.GET
Mock responses
# Show cached mock response.
php cli.php cache-get http-response_mock prvdr.example-service.ndpnt.GET

# Delete cached mock response.
php cli.php cache-delete http-response_mock prvdr.example-service.ndpnt.GET

, (*9)

, (*10)

#### ▹▹ Client error codes #### , (*11)

For every error code there's an equivalent prefab safe and user-friendly (localizable) error message., (*12)

  • unknown: overall error fallback
  • local-unknown: local error fallback
  • local-algo: in-package logical error
  • local-use: invalid argument et al.
  • local-configuration: bad config var
  • local-option: bad option var
  • local-init: RestMini Client or cURL cannot request
  • host-unavailable: DNS or actually no such host
  • service-unavailable: status 503 Service Unavailable
  • too-many-redirects: too many redirects
  • timeout: cURL 504
  • timeout-propagated: status 504 Gateway Timeout
  • response-none: cURL 500 (RestMini Client 'response-false')
  • remote: status 500 Internal Server Error
  • remote-propagated: remote says 502 Bad Gateway
  • malign-status-unexpected: unsupported 5xx status
  • endpoint-not-found: status 404 + Content-Type not JSON (probably HTML); no such endpoint
  • resource-not-found: status 204, status 404 + Content-Type JSON; no such resource (object)
  • remote-validation-bad: 400 Bad Request
  • remote-validation-failed: 412 Precondition Failed, 422 Unprocessable Entity
  • response-type: content type mismatch
  • response-format: parse error
  • benign-status-unexpected: unsupported non-5xx status
  • header-missing: setting/option require_response_headers
  • response-validation: response body validation failure; service will send X-Http-Response-Invalid header, (*13)

    , (*14)

, (*15)

, (*16)

▹ Service

, (*17)

Producing a service response is not as hard as requesting a remote service,
so the service part of Http is not as rich as the client part.
It is assumed that one will simply echo something and send some headers – or use a service framework like Slim., (*18)

The HttpServiceSlim class suggest means of interacting with Slim, and Http includes a simple example. @todo
And Http also provides a few other service utilities., (*19)

Allowing Cross Origin requests

Preferably only at development site. Necessary when developing Angular-based frontend., (*20)

Place a .cross_origin_allow_sites text file in document root, containing list allowed sites, like:
http://localhost:4200,http://my-project.build.local.host:80, (*21)

, (*22)

#### ▹▹ Service error codes #### , (*23)

For every error code there's an equivalent prefab safe and user-friendly (localizable) error message., (*24)

  • unknown: overall fallback
  • request-unacceptable: (some kind of) bad request; HttpResponseRequestUnacceptable
  • unauthenticated: authentication (login) failure; HttpResponseRequestUnauthenticated
  • unauthorized: authorization (permission) failure; HttpResponseRequestUnauthorized
  • request-validation: request header/argument validation failure; HttpResponseRequestInvalid
  • frontend-response-format: frontend only; parse error
  • frontend-response-validation: frontend only; response validation failure, (*25)

    , (*26)

, (*27)

Service and client combined

Standardized wrapped response body

A service requestor should never be in doubt whether a request to your service went alltogether well.
HttpClient->request() returns HttpResponse object:, (*28)

  • status int: suggested status to send to requestor
  • headers array: suggested headers to send
  • body HttpResponseBody
    • success bool
    • status int: status received from remote service
    • data mixed|null: that actual data (on success)
    • message string|null: safe and user-friendly message (on failure)
    • code int: error code (on failure), or optionally some other flag (on success)
  • originalHeaders array: headers received – not to be sent to requestor
  • validated bool|null: whether the response was validated, and then the outcome

The general idea is to always send a response body containing metadata about the procedings – success, status, code.
And – on failure – a prefab safe and user-friendly message, which the client can use to inform the visitor
(instead of just failing silently/ungracefully)., (*29)

When exposing a service that does a remote request, the service should however have access to more detailed info about the remote request/response
– therefore the further wrapping in an object that suggests status and headers (et al.)., (*30)

, (*31)

▹ Service response headers

, (*32)

Http uses a number of custom response headers, to flag stuff to the client.
Some are issued by HttpClient upon every remote request (the original/final statuses).
Others are only issued if a service uses/sends one of the prefab HttpResponse extensions., (*33)

  • (int)X-Http-Original-Status: status received from remote service (or interpretated ditto)
  • (int)X-Http-Final-Status: final status to be sent to client
  • X-Http-Response-Invalid: response validation failure; HttpResponseResponseInvalid
  • X-Http-Mock-Response: HttpClient never called remote service; used prefab mock response
  • X-Http-Request-Invalid: request header/argument validation failure; HttpResponseRequestInvalid
  • X-Http-Request-Unacceptable: (some kind of) bad request; HttpResponseRequestUnacceptable
  • X-Http-Request-Unauthenticated: authentication (login) failure; HttpResponseRequestUnauthenticated
  • X-Http-Request-Unathorized: authorization (permission) failure; HttpResponseRequestUnauthorized

, (*34)

Requirements

Suggestions

The Versions

25/06 2018

dev-develop

dev-develop https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

25/06 2018

dev-master

9999999-dev https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

25/06 2018

2.0.1

2.0.1.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

24/06 2018

dev-feature-config-regime

dev-feature-config-regime https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

24/06 2018

2.0

2.0.0.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

19/06 2018

1.x-dev

1.9999999.9999999.9999999-dev https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

19/06 2018

1.2

1.2.0.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

16/06 2018

1.1.1

1.1.1.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

04/06 2018

1.1

1.1.0.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

01/05 2018

1.0.7

1.0.7.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

19/04 2018

dev-test-external-dic

dev-test-external-dic https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

22/11 2017

1.0.6

1.0.6.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

09/11 2017

1.0.5

1.0.5.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

24/10 2017

1.0.4

1.0.4.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

06/10 2017

1.0.3

1.0.3.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

05/10 2017

1.0.2

1.0.2.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

25/09 2017

1.0.1

1.0.1.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate

24/09 2017

1.0

1.0.0.0 https://github.com/simplecomplex/php-http

High-level HTTP client and (Slim) service utility. Client provides response validation and mocking; service provides standardized and predictable responses.

  Sources   Download

MIT

The Requires

 

by Jacob Friis Mathiasen

php http client http service http response mock http response validate