:mod:`magpie.services` ====================== .. py:module:: magpie.services Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: magpie.services.ServiceMeta magpie.services.ServiceInterface magpie.services.ServiceOWS magpie.services.ServiceWPS magpie.services.ServiceBaseWMS magpie.services.ServiceNCWMS2 magpie.services.ServiceGeoserverWMS magpie.services.ServiceAccess magpie.services.ServiceAPI magpie.services.ServiceWFS magpie.services.ServiceTHREDDS Functions ~~~~~~~~~ .. autoapisummary:: magpie.services.service_factory .. class:: ServiceMeta Bases: :class:`type` .. method:: resource_types(cls: Type[ServiceInterface]) -> List[models.Resource] :property: Allowed resources type classes under the service. .. method:: resource_type_names(cls: Type[ServiceInterface]) -> List[Str] :property: Allowed resources type names under the service. .. method:: child_resource_allowed(cls: Type[ServiceInterface]) -> bool :property: .. class:: ServiceInterface(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`object` .. attribute:: service_type :annotation: :Str .. attribute:: params_expected :annotation: :List[Str] = [] .. attribute:: permissions :annotation: :List[Permission] = [] .. attribute:: resource_types_permissions :annotation: :Dict[models.Resource, List[Permission]] .. method:: permission_requested(self) -> Optional[Union[Permission, Collection[Permission]]] :abstractmethod: Defines how to interpret the incoming request into :class:`Permission` definitions for the given service. Each service must implement its own definition. The method must specifically define how to convert generic request path, query, etc. elements into permissions that match the service and its children resources. If ``None`` is returned, the :term:`ACL` will effectively be resolved to denied access. Otherwise, one or more returned :class:`Permission` will indicate which permissions should be looked for to resolve the :term:`ACL` of the authenticated user and its groups. .. method:: resource_requested(self) -> Optional[Tuple[ServiceOrResourceType, bool]] :abstractmethod: Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. method:: user_requested(self) .. method:: __acl__(self) -> magpie.typedefs.AccessControlListType :property: Access Control List (:term:`ACL`) formed of :term:`ACE` defining combinations rules to grant or refuse access. Each :term:`ACE` is defined as ``(outcome, user/group, permission)`` tuples. Called by the configured Pyramid :class:`pyramid.authorization.ACLAuthorizationPolicy`. Caching is automatically handled according to configured application settings and whether the specific ACL combination being requested was already processed recently. .. method:: _get_acl_cached(self: magpie.typedefs.Str, request_method: magpie.typedefs.Str, request_path: Optional[int], user_id) -> magpie.typedefs.AccessControlListType Cache this method with :py:mod:`beaker` based on the provided caching key parameters. If the cache is not hit (expired timeout or new key entry), calls :meth:`ServiceInterface.get_acl` to retrieve effective permissions of the requested resource and specific permission for the applicable service and user executing the request. .. seealso:: - :meth:`ServiceInterface.permission_requested` - :meth:`ServiceInterface.resource_requested` - :meth:`ServiceInterface.user_requested` .. method:: _get_acl(self: magpie.models.User, user: magpie.typedefs.ServiceOrResourceType, resource: Collection[Permission], permissions: bool, allow_match=True) -> magpie.typedefs.AccessControlListType Resolves the resource-tree and the user/group inherited permissions into a simplified ACL for this resource. .. seealso:: - :meth:`effective_permissions` .. method:: _get_request_path_parts(self) -> Optional[List[Str]] Obtain the :attr:`request` path parts striped of anything prior to the referenced :attr:`service` name. .. method:: get_config(self) -> magpie.typedefs.ConfigDict Obtains the custom configuration of the registered service. .. method:: get_resource_permissions(cls: magpie.typedefs.Str, resource_type_name) -> List[Permission] :classmethod: Obtains the allowed permissions of the service's child resource fetched by resource type name. .. method:: allowed_permissions(self: magpie.typedefs.ServiceOrResourceType, resource) -> List[Permission] Obtains the allowed permissions for or under the service according to provided service or resource. .. method:: effective_permissions(self: magpie.models.User, user: magpie.typedefs.ServiceOrResourceType, resource: Optional[Collection[Permission]], permissions: bool = None, allow_match=True) -> List[PermissionSet] Obtains the effective permissions the user has over the specified resource. Recursively rewinds the resource tree from the specified resource up to the top-most parent service the resource resides under (or directly if the resource is the service) and retrieve permissions along the way that should be applied to children when using scoped-resource inheritance. Rewinding of the tree can terminate earlier when permissions can be immediately resolved such as when more restrictive conditions enforce denied access. Both user and group permission inheritance is resolved simultaneously to tree hierarchy with corresponding allow and deny conditions. User :term:`Direct Permissions` have priority over all its groups :term:`Inherited Permissions`, and denied permissions have priority over allowed access ones. All applicable permissions on the resource (as defined by :meth:`allowed_permissions`) will have their resolution (Allow/Deny) provided as output, unless a specific subset of permissions is requested using :paramref:`permissions`. Other permissions are ignored in this case to only resolve requested ones. For example, this parameter can be used to request only ACL resolution from specific permissions applicable for a given request, as obtained by :meth:`permission_requested`. Permissions scoped as `match` can be ignored using :paramref:`allow_match`, such as when the targeted resource does not exist. .. seealso:: - :meth:`ServiceInterface.resource_requested` .. class:: ServiceOWS(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceInterface` Generic request-to-permission interpretation method of various ``OGC Web Service`` (OWS) implementations. .. method:: resource_requested(self) :abstractmethod: Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. method:: permission_requested(self) -> magpie.permissions.Permission Defines how to interpret the incoming request into :class:`Permission` definitions for the given service. Each service must implement its own definition. The method must specifically define how to convert generic request path, query, etc. elements into permissions that match the service and its children resources. If ``None`` is returned, the :term:`ACL` will effectively be resolved to denied access. Otherwise, one or more returned :class:`Permission` will indicate which permissions should be looked for to resolve the :term:`ACL` of the authenticated user and its groups. .. class:: ServiceWPS(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceOWS` Service that represents a ``Web Processing Service`` endpoint. .. attribute:: service_type :annotation: = wps .. attribute:: permissions .. attribute:: params_expected :annotation: = ['service', 'request', 'version', 'identifier'] .. attribute:: resource_types_permissions .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. class:: ServiceBaseWMS(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceOWS` Service that represents basic capabilities of a ``Web Map Service`` endpoint. .. attribute:: permissions .. attribute:: params_expected :annotation: = ['service', 'request', 'version', 'layers', 'layername', 'dataset'] .. method:: resource_requested(self) :abstractmethod: Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. class:: ServiceNCWMS2(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceBaseWMS` Service that represents a ``Web Map Service`` endpoint with functionalities specific to ``ncWMS2`` . .. attribute:: service_type :annotation: = ncwms .. attribute:: resource_types_permissions .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. class:: ServiceGeoserverWMS(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceBaseWMS` Service that represents a ``Web Map Service`` endpoint with functionalities specific to ``GeoServer``. .. attribute:: service_type :annotation: = geoserverwms .. attribute:: resource_types_permissions .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. class:: ServiceAccess(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceInterface` .. attribute:: service_type :annotation: = access .. attribute:: permissions .. attribute:: params_expected :annotation: = [] .. attribute:: resource_types_permissions .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. method:: permission_requested(self) Defines how to interpret the incoming request into :class:`Permission` definitions for the given service. Each service must implement its own definition. The method must specifically define how to convert generic request path, query, etc. elements into permissions that match the service and its children resources. If ``None`` is returned, the :term:`ACL` will effectively be resolved to denied access. Otherwise, one or more returned :class:`Permission` will indicate which permissions should be looked for to resolve the :term:`ACL` of the authenticated user and its groups. .. class:: ServiceAPI(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceInterface` Service that provides resources per individual request path segments. .. attribute:: service_type :annotation: = api .. attribute:: permissions .. attribute:: params_expected :annotation: = [] .. attribute:: resource_types_permissions .. method:: resource_requested(self) -> Optional[Tuple[ServiceOrResourceType, bool]] Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. method:: permission_requested(self) Defines how to interpret the incoming request into :class:`Permission` definitions for the given service. Each service must implement its own definition. The method must specifically define how to convert generic request path, query, etc. elements into permissions that match the service and its children resources. If ``None`` is returned, the :term:`ACL` will effectively be resolved to denied access. Otherwise, one or more returned :class:`Permission` will indicate which permissions should be looked for to resolve the :term:`ACL` of the authenticated user and its groups. .. class:: ServiceWFS(: magpie.models.Service, service: pyramid.request.Request, request) Bases: :class:`magpie.services.ServiceOWS` Service that represents a ``Web Feature Service`` endpoint. .. attribute:: service_type :annotation: = wfs .. attribute:: permissions .. attribute:: params_expected :annotation: = ['service', 'request', 'version', 'typenames'] .. attribute:: resource_types_permissions .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. class:: ServiceTHREDDS(*_, **__) Bases: :class:`magpie.services.ServiceInterface` Service that represents a ``THREDDS Data Server`` endpoint. .. attribute:: service_type :annotation: = thredds .. attribute:: permissions .. attribute:: params_expected :annotation: = ['request'] .. attribute:: resource_types_permissions .. method:: get_config(self) -> magpie.typedefs.ConfigDict Obtains the custom configuration of the registered service. .. method:: get_path_parts(self) .. method:: resource_requested(self) Defines how to interpret the incoming request into the targeted :class:`model.Resource` for the given service. Each service must implement its own definition. The expected return value must be either of the following:: - (target-resource, True) when the exact resource is found - (parent-resource, False) when any parent of the resource is found - None when invalid request or not found resource The `parent-resource` indicates the *closest* higher-level resource in the hierarchy that would nest the otherwise desired `target-resource`. The idea behind this is that `Magpie` will be able to resolve the effective recursive permission even if not all corresponding resources were explicitly defined in the database. For example, if the request *would* be interpreted with the following hierarchy after service-specific resolution:: ServiceA Resource1 <== closest *existing* parent resource [Resource2] <== target (according to service/request resolution), but not existing in database A permission defined as Allow/Recursive on ``Resource1`` should normally allow access to ``Resource2``. If ``Resource2`` is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using `Magpie` can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in `Magpie`. Using the ``(parent-resource, False)`` will allow resolution of permission from the closest available parent. .. note:: In case of `parent-resource` returned, only `recursive`-scoped permissions will be considered, since the missing `target-resource` is the only one that should be checked for `match`-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit `target` resource whenever possible. If the returned resource is ``None``, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource. :returns: tuple of reference resource (target/parent), and enabled status of match permissions (True/False) .. method:: permission_requested(self) Defines how to interpret the incoming request into :class:`Permission` definitions for the given service. Each service must implement its own definition. The method must specifically define how to convert generic request path, query, etc. elements into permissions that match the service and its children resources. If ``None`` is returned, the :term:`ACL` will effectively be resolved to denied access. Otherwise, one or more returned :class:`Permission` will indicate which permissions should be looked for to resolve the :term:`ACL` of the authenticated user and its groups. .. data:: SERVICE_TYPE_DICT .. function:: service_factory(service: magpie.models.Service, request: pyramid.request.Request) -> magpie.services.ServiceInterface Retrieve the specific service class from the provided database service entry.