Build Service/Concepts/AttributeStorage

From openSUSE

Revision as of 19:58, 1 November 2009

NOTE: This is almost implemented and running at the opensuse.org instance. However, the interfaces and the system might still change until 1.7 release!

The attribute system of OBS is designed to allow to store simple informations to a package or project. An attribute needs to be specified first to allow it's usage. The attribute definition are organized within namespaces.

Possible usages of attributes are any kind of meta informations, like:

• Package maintenance status
• Links to external resources, for example bugreports or screenshots
• References to update resources

Any attribute can be used also as a marker for efficient searches. For example, give me all package sources called "glibc" which shall be updated on security updates.

The status of this concept is WIP, it is half implemented in svn, but not yet deployed on the server.

Everthing might change until final 1.7, but candidates are esp:

• move namespace and attribute type definition out of project _meta file.
• Current limitition that admin rights are required for attribute definitions in any case will go away.

A Attribute Definition

Implemented

A namespace and/or attribute must be specified in a project meta file. This looks like this:

<project ...
...
<attributes>
 <namespace name="OBS">
   <modifiable_by group="Admin"/>
 </namespace>
 
 <definition name="maintained" namespace="OBS">
   <default>
     <value>no</value>
     <value>0</value>
   </default>
   <allowed>
     <value>0</value>
     <value>no</value>
     <value>security_only</value>
     <value>full_maintenance</value>
   </allowed>
   <count>2</count> <! -- this attribute must always contain two values -->
   <modifiable_by user="demouser"/>
   <modifiable_by group="demogroup"/>
   <modifiable_by role="demorole"/>
  </definition>
   
 </attributes>
...
</project>

The namespace is only to be allowed to be defined at one place. To create a new namespace you will need admin rights.

The modifiable_by permissions inside of a namespace element specify who will be allowed to modify the attribute definitions inside of this namespace. "OBS" will be reserved namespace, which shall only be touched by the OBS developers, because shipped tools and the system relies on it.

The definition element is defining one attribute. All elements inside of it are optional.

An Attribute Setting

Attributes are stored in own meta data of a package or project. They can be reached via

/source/<project>/<package>/_attribute

A "GET" operation lists all attributes for a project or package, this can look like this

  <attributes>
    <attribute name="OBS:maintained" />
    <attribute name="OBS:bugnumbers">
      <value>12345</value>
      <value>0815</value>
    </attribute>
  </attributes>

A "POST" operation is used for modifing or creating the send attributes and a "DELETE" is for removing them again.

The API

Read and set attributes

The attributes are part of the package meta files and can be modified via them. However, to avoid to download and parse the entire meta file for just reading one attribute there will be a attribute api call.

It will also allow to modify attributes, even without write permissions to the meta file, if this is allowed in attribute type definition.

GET      /source/$PROJECT/_attribute[/$ATTRIBUTE_NAME]?with_default=1
GET      /source/$PROJECT/$PACKAGE/_attribute[/$ATTRIBUTE_NAME]?with_default=1&with_project=1

POST     /source/$PROJECT/_attribute
POST     /source/$PROJECT/$PACKAGE/_attribute

DELETE   /source/$PROJECT/_attribute[/$ATTRIBUTE_NAME]
DELETE   /source/$PROJECT/$PACKAGE/_attribute[/$ATTRIBUTE_NAME]

The leading $ATTRIBUTE_NAME is optional for GET and DELETE operations. If not set all attributes are affected. Please note that this only affects the attribute values, but not the definition or namespace declaration in project case.

The with_defaults parameter is allowed on GET operations to give the default value, if no other value is defined. with_project_value works similar, but is falling back to the project attribute value.

Search by attributes

OBS allows you to search for all packages or projects which provide a certain attribute or even bound to be set to a certain value via standard search/XPath interface:

GET /search/package?match=[attribute/@name="OBS:maintained"]

The result is a collection as usual:

<collection>
  <package project="openSUSE:11.2" name="libtheora">
    <attributes....
    ....
    </attributes>
  </package>    
  <package ....
  ...
  </package>
</collection>

Please note that it matches for a package independend if the attribute is set in the package or in the project.

Example definition as it might be used on openSUSE.org server

This is just a collection, based on ideas when talking to people:

<attributes>

 <namespace name="OBS">      <! -- exists in all OBS instances -->
   <modifiable_by role="Admin"/>
 </namespace>
 <namespace name="openSUSE"> <! -- exists only in opensuse.org OBS -->
   <modifiable_by group="Admin"/>
 </namespace>

 <! -- OBS global attributes -->
 <definition name="Maintained" namespace="OBS" >
   <count>0</count>
   <modifiable_by role="Admin"/>
 </definition>
 <definition name="UpdateProject" namespace="OBS" >
   <count>1</count>
   <modifiable_by role="Admin"/>
 </definition>
 <definition name="Screenshots" namespace="OBS" > <! -- unlimited number of values(URLs) -->
   <modifiable_by role="maintainer"/>
 </definition>

 <! -- openSUSE attributes -->
 <definition name="L3-Support" namespace="openSUSE" >
   <allowed>
     <value>no</value>
     <value>upstream_only</value>
     <value>security_only</value>
     <value>full_maintenance</value>
   </allowed>
   <count>1<count>
   <modifiable_by role="bugowner"/>
 </definition>

</attributes>