Package entropy :: Package services :: Module client :: Class WebService

Class WebService

source code


This is the Entropy Repository Web Services that proxies requests over
an Web Services answering to HTTP POST requests
(either over HTTP or over HTTPS) in the following form:

Given that repositories must ship with a file (in their repository
meta file "packages.db.meta", coming from the server-side repository
directory) called "packages.db.webservices"
(etpConst['etpdatabasewebservicesfile']) containing the HTTP POST base
URL (example: http://packages.sabayon.org/api).
The POST url is composed as follows:
    <base_url>/<method name>
Function arguments are then appended in JSON format, so that float, int,
strings and lists are correctly represented.
So, for example, if WebService exposes a method with the following
signature (with the base URL in example above):

    float get_vote(string package_name)

The URL referenced will be:

    http://packages.sabayon.org/api/get_vote

And the JSON dictionary will contain a key called "package_name" with
package_name value.
For methods requiring authentication, the JSON object will contain
"username" and "password" fields (clear text, so make sure to use HTTPS).

The Response depends on each specific method and it is given in JSON format
too, that is afterwards interpreted by the caller function, that will
always return the expected data format (see respective API documentation).
For more information about how to implement the Web Service, please see
the packages.git Sabayon repository, which contains a Pylons MVC web app.
In general, every JSON response must provide a 'code' field, representing
an HTTP-response alike return code (200 is ok, 500 is server error, 400 is
bad request, etc) and a 'message' field, containing the error message (if
no error, 'message' is usually empty). The RPC result is put inside the
'r' field.

This is a base class, and you should really implement a subclass providing
your own API methods, and use _method_getter().

Nested Classes
  WebServiceException
Base WebService exception class.
  UnsupportedService
Raised when Repository doesn't seem to support any Web Service feature.
  UnsupportedParameters
Raised when input parameters cannot be converted to JSON.
  RequestError
If the request cannot be satisfied by the remote web service.
  AuthenticationRequired
When a method requiring valid user credentials is called without being logged in.
  AuthenticationFailed
When credentials are stored locally but don't seem to work against the Web Service.
  MethodNotAvailable
When calling a remote method that is not available.
  MalformedResponse
If JSON response cannot be converted back to dict.
  UnsupportedAPILevel
If this client and the Web Service expose a different API level.
  MethodResponseError
If the request has been accepted, but its computation stopped for some reason.
  CacheMiss
If the request is not available in the on-disk cache.
Instance Methods
 
__init__(self, entropy_client, repository_id)
WebService constructor.
source code
 
enable_cache_aging(self, days)
Turn on on-disk cache aging support.
source code
 
add_credentials(self, username, password)
Add credentials for this repository and store the information into an user-protected location.
source code
 
validate_credentials(self)
Validate currently stored credentials (if available) against the remote service.
source code
bool
credentials_available(self)
Return whether credentials are stored locally or not.
source code
string or None
get_credentials(self)
Return the username string stored in the authentication storage, if any.
source code
bool
remove_credentials(self)
Remove any credential bound to the repository from on-disk storage.
source code
 
service_available(self, cache=True, cached=False)
Return whether the Web Service is correctly able to answer our requests.
source code
 
data_send_available(self)
Return whether data send is correctly working.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Methods
 
config(cls, repository_id)
Return the WebService configuration for the given repository.
source code
Class Variables
  SUPPORTED_URL_SCHEMAS = ('http', 'https')
  PKG_ICON_IDENTIFIER = '__icon__'
  SUPPORTED_API_LEVEL = 1
  WEB_SERVICE_RESPONSE_CODE_OK = 200
  WEB_SERVICE_INVALID_CREDENTIALS_CODE = 450
  WEB_SERVICE_INVALID_REQUEST_CODE = 400
  WEB_SERVICE_NOT_FOUND_CODE = 404
  WEB_SERVICE_RESPONSE_ERROR_CODE = 503
  CACHE_DIR = '/var/lib/entropy/websrv_cache'
Properties

Inherited from object: __class__

Method Details

__init__(self, entropy_client, repository_id)
(Constructor)

source code 

WebService constructor. NOTE: This base class must NOT use any Entropy Client specific method and MUST rely on what is provided by it's parent class TextInterface.

Parameters:
  • entropy_client (entropy.client.interfaces.client.Client) - Entropy Client interface
  • repository_id - repository identifier
Overrides: object.__init__

config(cls, repository_id)
Class Method

source code 

Return the WebService configuration for the given repository. The object returned is a dictionary containing the following items:

  • url: the Entropy WebService base URL (or None, if not supported)
  • update_eapi: the maximum supported EAPI for repository updates.
  • repo_eapi: the maximum supported EAPI for User Generate Content.
Parameters:
  • repository_id (string) - repository identifier

enable_cache_aging(self, days)

source code 

Turn on on-disk cache aging support. If cache is older than given days, it will be removed and considered invalid.

validate_credentials(self)

source code 

Validate currently stored credentials (if available) against the remote service. If credentials are not available, WebService.AuthenticationRequired is raised. If credentials are not valid, WebService.AuthenticationFailed is raised.

Raises:

credentials_available(self)

source code 

Return whether credentials are stored locally or not. Please note that credentials can be stored properly but considered invalid remotely.

Returns: bool
True, if credentials are available

get_credentials(self)

source code 

Return the username string stored in the authentication storage, if any. Otherwise return None.

Returns: string or None
the username string stored in the authentication storage

remove_credentials(self)

source code 

Remove any credential bound to the repository from on-disk storage.

Returns: bool
True, if credentials existed and got removed

service_available(self, cache=True, cached=False)

source code 
Return whether the Web Service is correctly able to answer our requests.

@keyword cache: True means use on-disk cache if available?
@type cache: bool
@keyword cached: if True, it will only use the on-disk cached call
    result and raise WebService.CacheMiss if not found.
@type cached: bool
@return: True, if service is available
@rtype: bool

@raise WebService.UnsupportedParameters: if input parameters are invalid
@raise WebService.RequestError: if request cannot be satisfied
@raise WebService.MethodNotAvailable: if API method is not available
    remotely and an error occurred (error code passed as exception
    argument)
@raise WebService.AuthenticationRequired: if require_credentials is True
    and credentials are required.
@raise WebService.AuthenticationFailed: if credentials are not valid
@raise WebService.MalformedResponse: if JSON response cannot be
    converted back to dict.
@raise WebService.UnsupportedAPILevel: if client API and Web Service
    API do not match
@raise WebService.MethodResponseError; if method execution failed
@raise WebService.CacheMiss: if cached=True and cached object is not
    available

data_send_available(self)

source code 

Return whether data send is correctly working. A temporary file with random content is sent to the service, that would need to calculate its md5 hash. For security reason, data will be accepted remotely if, and only if its size is < 256 bytes.