Connections to MIMIQ

module MimiqLink end

This module contains convenience tools to establish and keep up a connection to the QPerfect MIMIQ services, both remote or on premises.

It allows for three different connection modes: via login page, via token, via credentials.

Login Page

This method will open a browser pointing to a login page. The user will be asked to insert username/email and password.

julia> using MimiqLink

julia> connection = MimiqLink.connect()

optionally an address for the MIMIQ services can be specified

julia> connection = MimiqLink.connect(url = "http://127.0.0.1")

Token

This method will allow the user to save a token file (by login via a login page), and then load it also from another julia session.

julia> using MimiqLink

julia> MimiqLink.savetoken(url = "http://127.0.0.1")

this will save a token in the qperfect.json file in the current directory. In another julia session is then possible to do:

julia> using MimiqLink

julia> connection = MimiqLink.loadtoken("path/to/my/qperfect.json")

Credentials

This method will allow users to access by directly use their own credentials.

julia> using MimiqLink

julia> connection = MimiqLink.connect("me@mymail.com", "myweakpassword")

julia> MimiqLink.connect("me@mymail.com", "myweakpassword"; url = "http://127.0.0.1")

const QPERFECT_CLOUD

Address for the QPerfect Cloud services

const QPERFECT_DEV

Address for secondary QPerfect Cloud services

abstract type AbstractConnection

Abstract type for the connection to the MIMIQ Services.

struct Execution

Structure referring to an execution on the MIMIQ Services.

struct MimiqConnection

Connection with the MIMIQ Services.

Attributes

• uri: the URI of the connected instance
• tokens_channel: channel updated with the latest refreshed token
• refresher: task that refreshes the token on a configured interval

PlanqkConnection

Represents a connection to the PlanQK API.

struct QhiveConnection

Connection with the Quantum Hive Services.

Attributes

• uri: the URI of the connected instance
• authuri: the URI of the identity provider
• realm: the Keycloak realm used for authentication
• clientid: the Keycloak client the library authenticates as
• tokens_channel: channel updated with the latest refreshed token
• refresher: task that refreshes the token before it expires

connect([; url=QPREFECT_CLOUD])
connect(token[; url=QPREFECT_CLOUD])
connect(username, password[; url=QPREFECT_CLOUD])

connect(PlanqkConnection, url, consumer_key, consumer_secret)
connect(PlanqkConnection)

connect(QhiveConnection)
connect(QhiveConnection, token)
connect(QhiveConnection, email, password)

Establish a connection to the MIMIQ Services.

The first three methods return a MimiqConnection.

The PlanqkConnection methods return a PlanqkConnection, effectively connecting through PlanQK.

The QhiveConnection methods return a QhiveConnection, connecting to the Quantum Hive services through their Keycloak identity provider. See connect(::Type{QhiveConnection}) for their keyword arguments.

A refresh process will be spawned in the background to refresh the access credentials. An active connection can be closed by using the close(connection) method. As an example:

connection = connect("john.doe@example.com", "johnspassword")
# connecton will be of type MimiqConnection
close(connection)

There are two main servers for the MIMIQ Services: the main one and a secondary one. Users are supposed to use the main one.

julia> QPERFECT_CLOUD
URI("https://mimiq.qperfect.io")

julia> QPERFECT_DEV
URI("https://mimiqfast.qperfect.io")

connect(QhiveConnection[; url, authurl, realm, clientid])
connect(QhiveConnection, token[; url, authurl, realm, clientid])
connect(QhiveConnection, email, password[; url, authurl, realm, clientid])

Establish a connection to the Quantum Hive Services.

Authentication goes through Keycloak. The first method opens a login page in the default browser, the second reuses a refresh token obtained earlier, and the third signs in directly with an email and a password.

A refresh process is spawned in the background to refresh the access token before it expires. Close the connection with close(connection), which also ends the session on the identity provider.

Keyword arguments

• url: the URI of the Quantum Hive services (default: QPERFECT_DEV)
• authurl: the URI of the identity provider (default: url with /auth)
• realm: the Keycloak realm (default: QHIVE_REALM)
• clientid: the Keycloak client (default: QHIVE_CLIENT_ID)

Examples

julia> connection = connect(QhiveConnection)

julia> close(connection)

deletefiles(conn, req)

Delete the uploaded and result files associated with a request.

downloadjobfiles(conn, req[, destdir])

Download the uploaded input files for a given execution request.

Files are saved to destdir, which defaults to ./{execution_id}/.

Returns a Vector{String} of downloaded file paths.

See also downloadresults.

downloadresults(conn, req[, destdir])

Download the result files for a given execution request.

Files are saved to destdir, which defaults to ./{execution_id}/.

Returns a Vector{String} of downloaded file paths.

See also downloadjobfiles.

isjobcanceled(conn, execution)

Check if a job has been canceled.

isjobdone(conn, execution)

Check if a job is done.

Will return true if the job finished successfully, with an error, or was canceled, and false otherwise.

isjobfailed(conn, execution)

Check if a job failed.

isjobstarted(conn, execution)

Check if a job has started executing.

loadtoken([filename])

Establish a connection to the MIMIQ Services by loading the credentials from a JSON file.

Arguments

• filename: file where to load the credentials (default: qperfect.json)

The credentials are usually valid only for a small amount of time, so you may need to regenerate them from time to time.

Examples

julia> savetoken("myqperfectcredentials.json")

julia> connection = loadtoken("myqperfectcredentials.json")

printrequests(conn; kwargs...)

Print the list of requests on the MIMIQ Cloud Services.

Keyword arguments

• status: filter by status. Can be NEW, RUNNING, ERROR, CANCELED, DONE.
• userEmail: filter by user email.
• limit: limit the number of requests to retrieve. Can be [10, 50, 100, 200].
• page: page number to retrieve.

requestinfo(conn, req)

Retrieve information about an execution request.

requests(conn; kwargs...)

Retrieve the list of requests on the MIMIQ Cloud Services.

Keyword arguments

• status: filter by status. Can be NEW, RUNNING, ERROR, CANCELED, DONE.
• userEmail: filter by user email.
• limit: limit the number of requests to retrieve. Can be [10, 50, 100, 200].
• page: page number to retrieve.

savetoken([filename][; url=QPERFECT_CLOUD)

Establish a connection to the MIMIQ Services and save the credentials in a JSON file.

Arguments

• filename: file where to save the credentials (default: qperfect.json)

Keyword arguments

• url: the uri of the MIMIQ Services (default: QPERFECT_CLOUD value)

Examples

julia> savetoken("myqperfectcredentials.json")

julia> connection = loadtoken("myqperfectcredentials.json")

stopexecution(conn, req)

Stop the execution of a request.

If the job is NEW, it will be immediately canceled. If it is RUNNING, a stop signal will be sent to the executor.