Implement Actions API.

[K0Te]

Closes #458

Hi @phadej ,

I've implemented just ~5% of Actions API at the moment. I have many questions and need your guidance before proceeding further:

• GitHub has changed documentation URLs, I am using new ones in the PR. Is it ok? It's probably worth changing all URLs in the repo, as GitHub has broken redirect a little bit, for example, https://developer.github.com/v3/pulls/#get-a-single-pull-request is forwarded to https://docs.github.com/en/rest/reference/pulls#get-a-single-pull-request instead of https://docs.github.com/en/rest/reference/pulls#get-a-pull-request . This should probably be a separate issue/PR.
• Response style is different for actions API, JSON includes tagged item list and a total count:

{
  "artifacts": [
   ...
  ],
  "total_count": 13676
}

I see three ways of handling this:

1. A separate Response type for each list endpoint, it's simple but need a lot of code:

data ArtifactList = ArtifactList
    { artifactListArtifacts :: !(Vector Artifact)
    , artifactListTotalCount :: !Int
    }
    deriving (Show, Data, Typeable, Eq, Ord, Generic

2. Tag as a type-level symbol, this looks nicer, but needs extensions and moves tag towards Endpoints instead of Data:

data PaginatedWithTotalCount a (tag :: Symbol) = PaginatedWithTotalCount
    { paginatedWithTotalCountItems :: !(Vector a)
    , paginatedWithTotalCountTotalCount :: !Int
    }

3. Tag defined in instance declaration for each paginated type. This approach seems best, but might break if GitHub API uses different tags for the same type - in this case, the library would need new types, which will be confusing...

data WithTotalCount a = WithTotalCount
    { withTotalCountItems :: !(Vector a)
    , withTotalCountTotalCount :: !Int
    } deriving (Show, Data, Typeable, Eq, Ord, Generic)

instance Semigroup (WithTotalCount a) where
    (WithTotalCount items1 count1) <> (WithTotalCount items2 _) =
        WithTotalCount (items1 <> items2) count1

instance Foldable WithTotalCount where
    foldMap f (WithTotalCount items _) = foldMap f items

instance FromJSON (WithTotalCount Artifact) where
    parseJSON = withObject "ArtifactList" $ \o -> WithTotalCount
        <$> o .: "artifacts"
        <*> o .: "total_count

• Tests. I have implemented tests for reading the artifact list. Downloading is more complex - it needs workflow permissions and does not work with an empty token. Even if https://github.com/phadej/github contained actions with artifacts, other users won't be able to run integration tests with download and deletion. Should I test only API with minimal required permissions?

[phadej]

What are these? Is artifacts pagination different then for everything else?

[K0Te]

Yes, please check my comment above. At least I didn't find existing implementation for this pagination style.

[K0Te]

Hi @andreasabel ,

I got back to this issue and hope to implement full support for GitHub Actions.
Hope you could review this PR once it's ready and help to merge it.
There is one more interesting issue with the Actions API - https://docs.github.com/en/rest/actions/cache#delete-github-actions-caches-for-a-repository-using-a-cache-key defines a DELETE request with query parameters but at the moment only Queries support query parameters. Adding query parameters to command or Command would require changing lots of code, could there be a better approach?

[andreasabel]

Hi @K0Te, good to have you back on track!

Hope you could review this PR once it's ready and help to merge it.

I'll do my best. I am not really an expert on this package.
Make sure your functionality is covered by tests or examples, remember to document, and adhere to the current style of the API, please.

There is one more interesting issue ... at the moment only Queries support query parameters.
Adding query parameters to command or Command would require changing lots of code, could there be a better approach?

I suppose you are referring to this code:

github/src/GitHub/Data/Request.hs

Lines 155 to 164 in 01c1154

	data GenRequest (mt :: MediaType *) (rw :: RW) a where
	Query :: Paths -> QueryString -> GenRequest mt rw a
	PagedQuery :: (a ~ t b, Foldable t, Semigroup a) => Paths -> QueryString -> FetchCount -> GenRequest mt rw a
	-- | Command
	Command
	:: CommandMethod -- ^ command
	-> Paths -- ^ path
	-> LBS.ByteString -- ^ body
	-> GenRequest mt 'RW a

github/src/GitHub/Data/Request.hs

Lines 174 to 181 in 01c1154

	query :: Paths -> QueryString -> Request mt a
	query ps qs = Query ps qs
	pagedQuery :: FromJSON a => Paths -> QueryString -> FetchCount -> Request mt (Vector a)
	pagedQuery ps qs fc = PagedQuery ps qs fc
	command :: CommandMethod -> Paths -> LBS.ByteString -> Request 'RW a
	command m ps body = Command m ps body

To keep API breakage at bay, I'd add it to Command but keep the smart constructor command as-is. Add a new smart constructor (e.g. paramCommand) that exposes the full feature set of Command.

[andreasabel]

I resolved the conflicts with master so that CI can run.

[K0Te]

Hi @andreasabel ,

This PR is finally ready for review! 🚀
I have tested all endpoints added in the scope of this PR, everything seems to work fine on my test repo.
Some GitHub Actions API features are missing, so implementation does not cover all available API. However, I think that is should be enough for most use cases. Missing endpoints:

• https://docs.github.com/en/rest/actions/self-hosted-runner-groups
• https://docs.github.com/en/rest/actions/self-hosted-runners
• https://docs.github.com/en/rest/actions/permissions
• Enterprise-level endpoints for Cache
• https://docs.github.com/en/rest/actions/cache#delete-github-actions-caches-for-a-repository-using-a-cache-key - see discussions above, cache can be deleted by Id using an alternative endpoint

[K0Te]

@andreasabel reminding about this PR ^_^

[andreasabel]

Thanks for the PR! and sorry for the delayed review.

I had some stylistic requests but fixed them myself.

What remains is to document the WithTotalCount type.

[andreasabel]

Candidate for 0.29 at: https://hackage.haskell.org/package/github-0.29/candidate

[andreasabel]

Addressed the last bits.

Good to go!

[andreasabel]

Published at https://hackage.haskell.org/package/github-0.29

Big thanks, @K0Te !