Code Monkey home page Code Monkey logo

apple-notary-api-kotlin-client's Introduction

apple-notary-api-kotlin-client

JetBrains team project Github Build GitHub license

Apple Notary API client for Kotlin.

Notarize your macOS application from Kotlin code without dependency on Xcode nor macOS.

Add the dependency

This library is available on Space Packages, you will need to add this Maven repository to your Gradle configuration:

import java.net.URI

repositories {
    maven {
        url = URI("https://packages.jetbrains.team/maven/p/ij/intellij-dependencies")
    }
}

Then add the dependency

implementation("org.jetbrains:apple-notary-api-kotlin-client:$version")

You will also need to provide a Ktor engine implementation, for example if you want to use the CIO engine:

implementation("io.ktor:ktor-client-cio:$ktorVersion")

Usage

You will first need to create an API Key for App Store Connect API, see Apple's Documentation . While doing this process make sure to save:

  • your issuer ID from the API Keys page in App Store Connect (e.g. 57246542-96fe-1a63-e053-0824d011072a)
  • your private key ID from App Store Connect (e.g. 2X9R4HXF34)
  • your private key .p8 file you can download from the API Keys page in App Store Connect

Once you have these information, you can setup a credential object:

import com.jetbrains.notary.NotaryClientV2
import com.jetbrains.notary.auth.AppStoreConnectAPIKey

val credentials = AppStoreConnectAPIKey(
    issuerId = "your-issuer-id",
    keyId = "your-private-key-id",
    privateKey = "your-private-key-file-content",
)

val client = NotaryClientV2(credentials)

// ... now you can use your client!

// For example retrieving your previous submissions:
val submissions = client.getPreviousSubmissions()
println(submissions)

Extensions

apple-notary-api-kotlin-client provides some extension functions that cover basic use cases of Apple Notary API.

Functions notarize or notarizeBlocking

notarize (or its blocking equivalent notarizeBlocking) will cover the basic use case of "I want to notarize a file, wait for the notarization to complete, get status and logs of the submission result when completed". Under the hood, it will do the following:

  • Issue a notarization submission for the specified file
  • Upload the specified file to the location asked by Apple Notary API
  • Poll Apple Notary API until the submission completes (or timeout)
    • Note: with configuration such as ignoreServerError and ignoreTimeoutExceptions set to true (set by default), polling will be hardened not to fail on usual false negative situations
  • Fetch logs of the completed submission (whether it is a success or a failure)
  • Return status and logs of the completed submission
Example usage snippet
import com.jetbrains.notary.NotaryClientV2
import com.jetbrains.notary.auth.AppStoreConnectAPIKey
import kotlin.time.Duration.Companion.minutes

val credentials = AppStoreConnectAPIKey(
    issuerId = "your-issuer-id",
    keyId = "your-private-key-id",
    privateKey = "your-private-key-file-content",
)

val notaryApiClient = NotaryClientV2(credentials)
val notarizationResult = notaryApiClient.notarizeBlocking(file, StatusPollingConfiguration(
    timeout = 30.minutes,
    pollingPeriod = 1.minutes,
    ignoreServerError = true,
    ignoreTimeoutExceptions = true,
))

val json = Json { prettyPrint = true }
println("Notarization logs:\n${json.encodeToString(notarizationResult.logs)}")

when (notarizationResult.status) {
    SubmissionResponse.Status.ACCEPTED -> println("Notarization of $file successful")
    SubmissionResponse.Status.IN_PROGRESS, null -> error("Timed out polling status of $file notarization submission")
    SubmissionResponse.Status.INVALID, SubmissionResponse.Status.REJECTED -> error("Notarization of $file failed, see logs above")
}

Configuration

Use your own ktor client implementation

You are free to use your own ktor client implementation and thus configuration. We provide NotaryClientV2.defaultHttpClient to allow your client configuration to extend the default one.

Example of configuration: change retry policy
import com.jetbrains.notary.NotaryClientV2
import com.jetbrains.notary.auth.AppStoreConnectAPIKey
import kotlin.time.Duration.Companion.minutes

val credentials = AppStoreConnectAPIKey(
  issuerId = "your-issuer-id",
  keyId = "your-private-key-id",
  privateKey = "your-private-key-file-content",
)

val myOwnClient = NotaryClientV2.defaultHttpClient.config { // keep all the default configuration
  install(HttpRequestRetry) {
    retryOnExceptionOrServerErrors(maxRetries = 10) // but increase the number of retry of the default configuration
    constantDelay(millis = 1.minutes.inWholeMilliseconds) // but change the default exponential retry by a constant one
  }
}

val notaryApiClient = NotaryClientV2(credentials, httpClient = myOwnClient)

License

This project is distributed under the Apache 2.0 license.

Acknowledgment

Special thanks to the people that built Rust library apple-codesign that inspired this work.

apple-notary-api-kotlin-client's People

Contributors

archangelx360 avatar dmpanov avatar kropp avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

apple-notary-api-kotlin-client's Issues

Make default HttpClient retry exceptions and server errors

NotaryAPI backend server often fails with 5xx and/or connection timeouts, by default, we should retry these using an exponential delay to improve the reliability of our client.

We should also retryDelayAfterFailure as it is will become redundant.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.