Commit 5e9e4c6c authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'missing-docstrings'

e48a8ea7 types: add missing docstrings
6e3cfb3a webhooks: add missing dochooks
a935eb43 macros: add missing docstrings
22d4f4d2 systemhooks: add missing docstrings
67588381 hooks: add missing docstrings
032f6d6e webhooks: use ObjectId for commit SHAs
650c7785 types: remove Serialize constraint for UserResult
469100fa

 types: add missing trailing comma
...
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Reviewed-by: Brad King's avatarBrad King <brad.king@kitware.com>
Merge-request: !59
parents a4efa5c4 e48a8ea7
......@@ -6,6 +6,13 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! Hook structures
//!
//! Hooks are received from Gitlab when registered as a system or web hook listener.
//!
//! Gitlab does not have consistent structures for its hooks, so they often change from
//! version to version.
extern crate serde;
use self::serde::{Deserialize, Deserializer};
use self::serde::de::Error;
......@@ -17,8 +24,11 @@ use super::systemhooks::SystemHook;
use super::webhooks::WebHook;
#[derive(Debug, Clone)]
/// A deserializable structure for all Gitlab hooks.
pub enum GitlabHook {
/// A system hook.
System(SystemHook),
/// A web hook from a specific project.
Web(WebHook),
}
......
......@@ -38,6 +38,7 @@ macro_rules! impl_id {
macro_rules! enum_serialize {
( $name:ident -> $desc:expr, $( $value:ident => $str:expr, )+ ) => {
impl $name {
/// String representation of the variant.
pub fn as_str(&self) -> &'static str {
match *self {
$( $name::$value => $str, )*
......
......@@ -6,4 +6,12 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! System hook structures
//!
//! These hooks are received from Gitlab when registered as a system hook in the administrator
//! settings. Only administrators may create such hooks.
//!
//! Gitlab does not have consistent structures for its hooks, so they often change from
//! version to version.
include!(concat!(env!("OUT_DIR"), "/systemhooks.rs"));
......@@ -20,10 +20,15 @@ use super::types::{AccessLevel, GroupId, ObjectId, ProjectId, SshKeyId, UserId};
use super::webhooks::{CommitHookAttrs, ProjectHookAttrs};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur at the project level.
pub enum ProjectEvent {
/// A project was created.
Create,
/// A project was deleted.
Destroy,
/// A project was renamed.
Rename,
/// A project moved from one namespace to another.
Transfer,
}
enum_serialize!(ProjectEvent -> "project event",
......@@ -34,9 +39,13 @@ enum_serialize!(ProjectEvent -> "project event",
);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Visibility levels for projects.
pub enum ProjectVisibility {
/// The project is only visible to users who are logged in.
Internal,
/// The project is only visible to team members.
Private,
/// The project is visible to everyone.
Public,
}
enum_serialize!(ProjectVisibility -> "project visibility",
......@@ -46,24 +55,39 @@ enum_serialize!(ProjectVisibility -> "project visibility",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A hook for a project.
pub struct ProjectSystemHook {
/// The event which occurred.
pub event_name: ProjectEvent,
/// When the project was created.
pub created_at: DateTime<UTC>,
/// When the project was last updated.
pub updated_at: DateTime<UTC>,
/// The display name of the project.
pub name: String,
/// The email address of the owner.
pub owner_email: String,
/// The name of the owner.
pub owner_name: String,
/// The path of the project (used for URLs).
pub path: String,
/// The namespace and path of the project.
pub path_with_namespace: String,
/// The ID of the project.
pub project_id: ProjectId,
/// The visibility level of the project.
pub project_visibility: ProjectVisibility,
/// The old namespace and path of the project for `Rename` and `Transfer` events.
pub old_path_with_namespace: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur when users are added and removed from projects.
pub enum ProjectMemberEvent {
/// A user was added to a project.
Add,
/// A user was removed from a project.
Remove,
}
enum_serialize!(ProjectMemberEvent -> "project member event",
......@@ -106,25 +130,42 @@ impl From<HumanAccessLevel> for AccessLevel {
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A project membership hook.
pub struct ProjectMemberSystemHook {
/// The event which occurred.
pub event_name: ProjectMemberEvent,
/// When the membership was created.
pub created_at: DateTime<UTC>,
/// When the membership was last updated.
pub updated_at: DateTime<UTC>,
/// The name of the project.
pub project_name: String,
/// The path of the project (used for URLs).
pub project_path: String,
/// The namespace and path of the project (used for URLs).
pub project_path_with_namespace: String,
/// The ID of the project.
pub project_id: ProjectId,
/// The username of the user added as a member.
pub user_username: String,
/// The name of the user added as a member.
pub user_name: String,
/// The email address of the user added as a member.
pub user_email: String,
/// The ID of the user.
pub user_id: UserId,
/// The access level granted to the user.
pub access_level: HumanAccessLevel,
/// The visibility of the project.
pub project_visibility: ProjectVisibility,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur for user accounts.
pub enum UserEvent {
/// The user account was created.
Create,
/// The user account was deleted.
Destroy,
}
enum_serialize!(UserEvent -> "user event",
......@@ -133,19 +174,30 @@ enum_serialize!(UserEvent -> "user event",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A user hook.
pub struct UserSystemHook {
/// The event which occurred.
pub event_name: UserEvent,
/// When the user account was created.
pub created_at: DateTime<UTC>,
/// When the user account was last updated.
pub updated_at: DateTime<UTC>,
/// The name of the user.
pub name: String,
/// The email address of the user.
pub email: String,
/// The ID of the user.
pub user_id: UserId,
/// The username of the user.
pub username: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur for SSH keys.
pub enum KeyEvent {
/// An SSH key was uploaded.
Create,
/// An SSH key was deleted.
Destroy,
}
enum_serialize!(KeyEvent -> "key event",
......@@ -154,18 +206,28 @@ enum_serialize!(KeyEvent -> "key event",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// An SSH key hook.
pub struct KeySystemHook {
/// The event which occurred.
pub event_name: KeyEvent,
/// When the key was added.
pub created_at: DateTime<UTC>,
/// When the key was last updated.
pub updated_at: DateTime<UTC>,
/// The username of the user.
pub username: String,
/// The content of the key.
pub key: String,
/// The ID of the key.
pub id: SshKeyId,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur for groups.
pub enum GroupEvent {
/// The group was created.
Create,
/// The group was deleted.
Destroy,
}
enum_serialize!(GroupEvent -> "group event",
......@@ -174,20 +236,32 @@ enum_serialize!(GroupEvent -> "group event",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A group hook.
pub struct GroupSystemHook {
/// The event which occurred.
pub event_name: GroupEvent,
/// When the group was created.
pub created_at: DateTime<UTC>,
/// When the group was last updated.
pub updated_at: DateTime<UTC>,
/// The name of the group.
pub name: String,
/// The path of the group (used for URLs).
pub path: String,
/// The ID of the group.
pub group_id: GroupId,
/// The email address of the owner of the group.
pub owner_email: Option<String>,
/// The name of the owner of the group.
pub owner_name: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur for group memberships.
pub enum GroupMemberEvent {
/// A user was added to the group.
Add,
/// A user was removed from the group.
Remove,
}
enum_serialize!(GroupMemberEvent -> "group member event",
......@@ -196,23 +270,38 @@ enum_serialize!(GroupMemberEvent -> "group member event",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A group membership hook.
pub struct GroupMemberSystemHook {
/// The event which occurred.
pub event_name: GroupMemberEvent,
/// When the group membership was added.
pub created_at: DateTime<UTC>,
/// When the group membership was last updated.
pub updated_at: DateTime<UTC>,
/// The name of the group.
pub group_name: String,
/// The path of the group (used for URLs).
pub group_path: String,
/// The ID of the group.
pub group_id: GroupId,
/// The username of the user.
pub user_username: String,
/// The name of the user.
pub user_name: String,
/// The email address of the user.
pub user_email: String,
/// The ID of the user.
pub user_id: UserId,
/// The access level of the user.
pub group_access: HumanAccessLevel,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Events which occur when a push happens.
pub enum PushEvent {
/// A non-tag push occurred.
Push,
/// A tag was pushed.
TagPush,
}
enum_serialize!(PushEvent -> "push event",
......@@ -221,34 +310,61 @@ enum_serialize!(PushEvent -> "push event",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A push hook.
pub struct PushSystemHook {
/// The event which occurred.
pub event_name: PushEvent,
/// When the push occurred.
pub created_at: DateTime<UTC>,
/// When the push
pub updated_at: DateTime<UTC>,
/// The old object ID of the ref that was pushed.
pub before: ObjectId,
/// The new object ID of the ref that was pushed.
pub after: ObjectId,
#[serde(rename="ref")]
/// The name of the reference that was pushed.
pub ref_: String,
/// The new object ID of the ref that was pushed.
pub checkout_sha: ObjectId,
/// The message for the push (used for annotated tags).
pub message: Option<String>,
/// The ID of the user who pushed.
pub user_id: UserId,
/// The name of the user who pushed.
pub user_name: String,
/// The email address of the user who pushed.
pub user_email: String,
/// The URL of the user's avatar.
pub user_avatar: String,
/// The ID of the project pushed to.
pub project_id: ProjectId,
/// Attributes of the project.
pub project: ProjectHookAttrs,
pub commits: Vec<CommitHookAttrs>, // limited to 20 commits
/// The commits pushed to the repository.
///
/// Limited to 20 commits.
pub commits: Vec<CommitHookAttrs>,
/// The total number of commits pushed.
pub total_commits_count: u64,
}
#[derive(Debug, Clone)]
/// A deserializable structure for all Gitlab system hooks.
pub enum SystemHook {
/// A project hook.
Project(ProjectSystemHook),
/// A project membership hook.
ProjectMember(ProjectMemberSystemHook),
/// A user account hook.
User(UserSystemHook),
/// An SSH key hook.
Key(KeySystemHook),
/// A group hook.
Group(GroupSystemHook),
/// A group membership hook.
GroupMember(GroupMemberSystemHook),
/// A push hook.
Push(PushSystemHook),
}
......@@ -257,15 +373,14 @@ impl Deserialize for SystemHook {
let val = try!(Value::deserialize(deserializer));
let event_name = match val.pointer("/event_name") {
Some(&Value::String(ref name)) => name,
Some(_) => {
return Err(D::Error::invalid_type(Type::String));
},
None => {
return Err(D::Error::missing_field("event_name"));
},
}
.to_string();
Some(&Value::String(ref name)) => name.to_string(),
Some(_) => {
return Err(D::Error::invalid_type(Type::String));
},
None => {
return Err(D::Error::missing_field("event_name"));
},
};
let hook_res = match event_name.as_str() {
"project_create" |
......
......@@ -6,4 +6,12 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! API entities
//!
//! These entities are exposed by Gitlab via its API.
//!
//! There are some places where Gitlab does not completely specify its types. This causes
//! problems when the types and names change inside of those. If found, issues should be filed
//! upstream.
include!(concat!(env!("OUT_DIR"), "/types.rs"));
This diff is collapsed.
......@@ -6,4 +6,11 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! Web hook structures
//!
//! These hooks are received from Gitlab when registered as a web hook within a project.
//!
//! Gitlab does not have consistent structures for its hooks, so they often change from
//! version to version.
include!(concat!(env!("OUT_DIR"), "/webhooks.rs"));
......@@ -21,6 +21,10 @@ use super::types::{BuildId, IssueId, IssueState, MergeRequestId, MergeRequestSta
UserId};
#[derive(Debug, Clone, Copy)]
/// A wrapper struct for dates in web hooks.
///
/// Gitlab does not use a standard date format for dates in web hooks. This structure supports
/// deserializing the formats that have been observed.
pub struct HookDate(DateTime<UTC>);
impl Serialize for HookDate {
......@@ -90,24 +94,36 @@ pub struct ProjectWikiHookAttrs {
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// User information exposed in hooks.
pub struct UserHookAttrs {
/// The name of the user.
pub name: String,
/// The handle of the user.
pub username: String,
/// The URL to the avatar of the user.
pub avatar_url: String,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// The identity of a user exposed through a hook.
pub struct HookCommitIdentity {
/// The name of the author or committer.
pub name: String,
/// The email address of the author or committer.
pub email: String,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// Commit information exposed in hooks.
pub struct CommitHookAttrs {
/// The commit's ID.
pub id: ObjectId,
/// The commit message.
pub message: String,
pub timestamp: DateTime<UTC>,
/// The URL of the commit.
pub url: String,
/// The author of the commit.
pub author: HookCommitIdentity,
pub added: Option<Vec<String>>,
pub modified: Option<Vec<String>>,
......@@ -115,29 +131,51 @@ pub struct CommitHookAttrs {
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// A push hook.
pub struct PushHook {
/// The event which occurred.
pub object_kind: String,
/// The old object ID of the ref before the push.
pub before: ObjectId,
/// The new object ID of the ref after the push.
pub after: ObjectId,
#[serde(rename="ref")]
/// The name of the reference which has been pushed.
pub ref_: String,
/// The new object ID of the ref after the push.
pub checkout_sha: Option<ObjectId>,
/// The message for the push (used for annotated tags).
pub message: Option<String>,
/// The ID of the user who pushed.
pub user_id: UserId,
/// The name of the user who pushed.
pub user_name: String,
/// The email address of the user who pushed.
pub user_email: String,
/// The URL of the user's avatar.
pub user_avatar: String,
/// The ID of the project pushed to.
pub project_id: ProjectId,
/// Attributes of the project.
pub project: ProjectHookAttrs,
/// The commits pushed to the repository.
///
/// Limited to 20 commits.
pub commits: Vec<CommitHookAttrs>, // limited to 20 commits
/// The total number of commits pushed.
pub total_commits_count: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Actions which may occur on an issue.
pub enum IssueAction {
/// The issue was updated.
Update,
/// The issue was opened.
Open,
/// The issue was closed.
Close,
/// The issue was reopened.
Reopen,
}
enum_serialize!(IssueAction -> "issue action",
......@@ -148,47 +186,78 @@ enum_serialize!(IssueAction -> "issue action",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// Issue information exposed in hooks.
pub struct IssueHookAttrs {
/// The ID of the issue.
pub id: IssueId,
/// The title of the issue.
pub title: String,
/// The ID of the assignee of the issue.
pub assignee_id: Option<UserId>,
/// The ID of the author of the issue.
pub author_id: UserId,
/// The ID of the project.
pub project_id: ProjectId,
/// When the issue was created.
pub created_at: HookDate,
/// When the issue was last updated.
pub updated_at: HookDate,
/// When the issue was deleted.
pub deleted_at: Option<HookDate>,
/// When the issue is due.
pub due_date: Option<NaiveDate>,
/// The ID of the user which last updated the issue.
pub updated_by_id: Option<UserId>,
pub moved_to_id: Option<Value>, // ???
pub position: u64,
/// The branch name for the issue.
pub branch_name: Option<String>,
/// The description of the issue.
pub description: String,
/// The ID of the milestone of the issue.
pub milestone_id: Option<MilestoneId>,
/// The state of the issue.
pub state: IssueState,
/// The user-visible ID of the issue.
pub iid: u64,
/// Whether the issue is confidential or not.
pub confidential: bool,
pub lock_version: u64,
// It seems that notes miss these properties?
/// The URL of the issue.
pub url: Option<String>,
/// The type of action which caused the hook.
pub action: Option<IssueAction>,
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// An issue hook.
pub struct IssueHook {
/// The event which occurred.
pub object_kind: String,
/// The user which triggered the hook.
pub user: UserHookAttrs,
/// The project the hook was created for.
pub project: ProjectHookAttrs,
/// Attributes of the issue.
pub object_attributes: IssueHookAttrs,
/// The assignee of the issue.
pub assignee: Option<UserHookAttrs>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Actions which may occur on a merge request.
pub enum MergeRequestAction {
/// The merge request was updated.
Update,
/// The merge request was opened.
Open,
/// The merge request was closed.
Close,
/// The merge request was reopened.
Reopen,
/// The merge request was merged.
Merge,
}
enum_serialize!(MergeRequestAction -> "merge request action",
......@@ -200,11 +269,14 @@ enum_serialize!(MergeRequestAction -> "merge request action",
);
#[derive(Serialize, Deserialize, Debug, Clone)]
/// Merge parameters for a merge request.
pub struct MergeRequestParams {
force_remove_source_branch: Option<Value>, // sigh
}
impl MergeRequestParams {
/// Whether the author of the merge request indicated that the source branch should be deleted
/// upon merge or not.
// https://gitlab.com/gitlab-org/gitlab-ce/issues/20880
pub fn force_remove_source_branch(&self) -> bool {
self.force_remove_source_branch
......@@ -225,58 +297,96 @@ impl MergeRequestParams {
}
#[derive(Serialize, Deserialize, Debug, Clone)]
/// Merge request information exposed in hooks.
pub struct MergeRequestHookAttrs {
/// The source project of the merge request.
pub source: ProjectHookAttrs,
/// The target project of the merge request.
pub target: ProjectHookAttrs,
pub last_commit: Option<CommitHookAttrs>,
/// Whether the merge request is a work-in-progress or not.
pub work_in_progress: bool,
/// The object ID of the merge commit which is currently being handled.
pub in_progress_merge_commit_sha: Option<ObjectId>,
/// The ID of the merge request.
pub id: MergeRequestId,
/// The target branch of the merge request.
pub target_branch: String,
/// The ID of the target project.
pub target_project_id: ProjectId,
/// The source branch of the merge request.
pub source_branch: String,
/// The ID of the source project.
pub source_project_id: ProjectId,
/// The ID of the author of the merge request.
pub author_id: UserId,
/// The ID of the assignee of the merge request.
pub assignee_id: Option<UserId>,
/// The title of the merge request.
pub title: String,
/// When the merge request was created.
pub created_at: HookDate,
/// When the merge request was last updated.
pub updated_at: HookDate,
/// When the merge request was deleted.
pub deleted_at: Option<HookDate>,
/// When the merge request was locked.
pub locked_at: Option<HookDate>,
/// The ID of the user which last updated the merge request.
pub updated_by_id: Option<UserId>,
/// The object ID of the commit which merged the merge request.
pub merge_commit_sha: Option<ObjectId>,
pub merge_error: Option<Value>, // String?
/// The parameters for merging the merge request.
pub merge_params: MergeRequestParams,
/// The user which merged the merge request.
pub merge_user_id: Option<UserId>,
/// Whether the merge request will be merged once all builds succeed or not.
pub merge_when_build_succeeds: bool,
pub position: u64, // ???
// st_commits
// st_diffs
/// The milestone of the merge request.
pub milestone_id: Option<MilestoneId>,
pub oldrev: Option<ObjectId>,
/// The state of the merge request.
pub state: MergeRequestState,
/// The merge status of the merge request.
pub merge_status: MergeStatus,
/// The user-visible ID of the merge request.
pub iid: u64,
/// The description of the merge request.
pub description: Option<String>,