PGPainless/pgpainless
PGPainless/pgpainless
1
0
Fork 0
mirror of https://github.com/pgpainless/pgpainless.git synced 2024-11-14 16:32:06 +01:00
Code Issues Releases Wiki Activity

Add kDoc to Kotlin classes

Browse source
This commit is contained in:
Paul Schaub 2023-06-28 21:08:19 +02:00
parent 1b654ca353
commit 14d5ab14d2
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
9 changed files with 193 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/CertSynopsis.kt
View file

@ -8,6 +8,14 @@ import org.pgpainless.algorithm.RevocationState
import org.pgpainless.key.OpenPgpFingerprint
import java.util.*
/**
* A [CertSynopsis] is a proxy object containing information about a certificate.
*
* @param fingerprint [OpenPgpFingerprint] of the certificate
* @param expirationTime optional expiration time of the certificate
* @param revocationState [RevocationState] denoting whether the certificate is revoked or not
* @param userIds [Map] of user-ids on the certificate, along with their revocation states
*/
data class CertSynopsis(
val fingerprint: OpenPgpFingerprint,
val expirationTime: Date?,

23
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/Certification.kt
View file

@ -6,6 +6,20 @@ package org.pgpainless.wot.dijkstra.sq
import java.util.*
/**
* A [Certification] is a signature issued by one certificate over a datum on another target certificate.
* Such a datum could be either a user-id, or the primary key of the target certificate.
*
* @param issuer synopsis of the certificate that issued the [Certification]
* @param target synopsis of the certificate that is target of this [Certification]
* @param userId optional user-id. If this is null, the [Certification] is made over the primary key of the target.
* @param creationTime creation time of the [Certification]
* @param expirationTime optional expiration time of the [Certification]
* @param exportable if false, the certification is marked as "not exportable"
* @param trustAmount amount of trust the issuer places in the binding
* @param trustDepth degree to which the issuer trusts the target as trusted introducer
* @param regexes regular expressions for user-ids which the target is allowed to introduce
*/
data class Certification(
val issuer: CertSynopsis,
val target: CertSynopsis,
@ -18,6 +32,15 @@ data class Certification(
val regexes: RegexSet
) {
/**
* Construct a [Certification] with default values. The result is non-expiring, will be exportable and has a
* trust amount of 120, a depth of 0 and a wildcard regex.
*
* @param issuer synopsis of the certificate that issued the [Certification]
* @param target synopsis of the certificate that is target of this [Certification]
* @param targetUserId optional user-id. If this is null, the [Certification] is made over the primary key of the target.
* @param creationTime creation time of the [Certification]
*/
constructor(
issuer: CertSynopsis,
targetUserId: String?,

33
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/CertificationSet.kt
View file

@ -4,6 +4,17 @@
package org.pgpainless.wot.dijkstra.sq
/**
* A [CertificationSet] is a set of [Certifications][Certification] made by the same issuer, on the same
* target certificate.
* In some sense, a [CertificationSet] can be considered an edge in the web of trust.
*
* @param issuer synopsis of the certificate that issued the [Certifications][Certification]
* @param target synopsis of the certificate that is targeted by the [Certifications][Certification]
* @param certifications [MutableMap] keyed by user-ids, whose values are [MutableLists][MutableList] of
* [Certifications][Certification] that are calculated over the key user-id. Note, that the key can also be null for
* [Certifications][Certification] over the targets primary key.
*/
data class CertificationSet(
val issuer: CertSynopsis,
val target: CertSynopsis,
@ -11,11 +22,22 @@ data class CertificationSet(
companion object {
/**
* Create an empty [CertificationSet].
*
* @param issuer the certificate that issued the [Certifications][Certification].
* @param target the certificate that is targeted by the [Certifications][Certification].
*/
@JvmStatic
fun empty(issuer: CertSynopsis, target: CertSynopsis): CertificationSet {
return CertificationSet(issuer, target, HashMap())
}
/**
* Create a [CertificationSet] from a single [Certification].
*
* @param certification certification
*/
@JvmStatic
fun fromCertification(certification: Certification) : CertificationSet {
val set = empty(certification.issuer, certification.target)
@ -24,6 +46,12 @@ data class CertificationSet(
}
}
/**
* Merge the given [CertificationSet] into this.
* This method copies all [Certifications][Certification] from the other [CertificationSet] into [certifications].
*
* @param other [CertificationSet] with the same issuer fingerprint and target fingerprint as this object.
*/
fun merge(other: CertificationSet) {
if (other == this) {
return
@ -39,6 +67,11 @@ data class CertificationSet(
}
}
/**
* Add a single [Certification] into this objects [certifications].
*
* @param certification [Certification] with the same issuer fingerprint and target fingerprint as this object.
*/
fun add(certification : Certification) {
require(issuer.fingerprint == certification.issuer.fingerprint) { "Issuer fingerprint mismatch." }
require(target.fingerprint == certification.target.fingerprint) { "Target fingerprint mismatch." }

35
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/Depth.kt
View file

@ -4,22 +4,34 @@
package org.pgpainless.wot.dijkstra.sq
/**
* Depth of a trust signature.
*/
class Depth(val limit: Int?) : Comparable<Depth> {
companion object {
/**
* The target is trusted to an unlimited degree.
*/
@JvmStatic
fun unconstrained() : Depth {
return Depth(null)
}
/**
* The target is trusted to a limited degree.
*/
@JvmStatic
fun limited(limit: Int): Depth {
require(limit in 0..255) {
"Trust depth MUST be a value between 0 and 255."
require(limit in 0..254) {
"Trust depth MUST be a value between 0 and 254."
}
return Depth(limit)
}
/**
* Deduce the trust degree automatically.
*/
@JvmStatic
fun auto(limit: Int): Depth {
return if (limit == 255) {
@ -30,10 +42,18 @@ class Depth(val limit: Int?) : Comparable<Depth> {
}
}
/**
* Return true, if the [Depth] is unconstrained.
*/
fun isUnconstrained() : Boolean {
return limit == null
}
/**
* Decrease the trust depth by one and return the result.
* If the [Depth] is unconstrained, the result will still be unconstrained.
* @throws IllegalArgumentException if the [Depth] cannot be decreased any further
*/
fun decrease(value : Int) : Depth {
return if (isUnconstrained()) {
unconstrained()
@ -46,6 +66,9 @@ class Depth(val limit: Int?) : Comparable<Depth> {
}
}
/**
* Return the minimum [Depth] of this and the other [Depth].
*/
fun min(other: Depth) : Depth {
return if (compareTo(other) <= 0) {
this
@ -54,18 +77,18 @@ class Depth(val limit: Int?) : Comparable<Depth> {
}
}
override fun compareTo(o: Depth): Int {
override fun compareTo(other: Depth): Int {
return if (isUnconstrained()) {
if (o.isUnconstrained()) {
if (other.isUnconstrained()) {
0
} else {
1
}
} else {
if (o.isUnconstrained()) {
if (other.isUnconstrained()) {
-1
} else {
limit!!.compareTo(o.limit!!)
limit!!.compareTo(other.limit!!)
}
}
}

8
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/Network.kt
View file

@ -30,11 +30,19 @@ class Network(
}
}
/**
* The total number of edges on the network.
*
* @return number of edges
*/
val numberOfEdges: Int
get() {
return edges.values.sumOf { it.size }
}
/**
* The total number of signatures the network comprises.
*/
val numberOfSignatures: Int
get() {
return edges.values

41
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/Path.kt
View file

@ -6,14 +6,33 @@ package org.pgpainless.wot.dijkstra.sq
import kotlin.math.min
/**
* A [Path] comprises a root [CertSynopsis], a list of edges ([Certifications][Certification]), as well as a
* residual depth.
*
* @param root root of the path
* @param edges list of edges from the root to the target
* @param residualDepth residual depth that is decreased each time another edge is appended
*/
class Path(
val root: CertSynopsis,
val edges: MutableList<Certification>,
var residualDepth: Depth
) {
/**
* Construct a [Path] only consisting of the trust root.
* The [Path] will have an empty list of edges and an unconstrained residual [Depth].
*
* @param root trust root
*/
constructor(root: CertSynopsis) : this(
root, mutableListOf<Certification>(), Depth.unconstrained())
/**
* Current target of the path.
* This corresponds to the target of the last entry in the edge list.
*/
val target: CertSynopsis
get() {
return if (edges.isEmpty()) {
@ -23,6 +42,10 @@ class Path(
}
}
/**
* List of [CertSynopses][CertSynopsis] (nodes) of the path.
* The first entry is the [root]. The other entries are the targets of the edges.
*/
val certificates: List<CertSynopsis>
get() {
val certs: MutableList<CertSynopsis> = ArrayList()
@ -33,12 +56,23 @@ class Path(
return certs
}
/**
* The length of the path, counted in nodes.
* A path with a single edge between node A and B has length 2, the empty path with only a trust root has length 1.
*/
val length: Int
get() = edges.size + 1
/**
* List of edges.
*/
val certifications: List<Certification>
get() = ArrayList(edges)
/**
* Trust amount of the path.
* This corresponds to the smallest trust amount of any edge in the path.
*/
val amount: Int
get() = if (edges.isEmpty()) {
120
@ -50,6 +84,13 @@ class Path(
min
}
/**
* Append an edge to the path and decrease the [residualDepth] of the path by 1.
*
* @throws IllegalArgumentException if the target at the end of the path is not equal to the issuer of the edge.
* @throws IllegalArgumentException if the path runs out of residual depth
* @throws IllegalArgumentException if the addition of the [Certification] would result in a cyclic path
*/
fun append(certification: Certification) {
require(target.fingerprint == certification.issuer.fingerprint) {
"Cannot append certification to path: Path's tail is not issuer of the certification."

23
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/Paths.kt
View file

@ -4,11 +4,23 @@
package org.pgpainless.wot.dijkstra.sq
/**
* List of individual [Paths][Path].
*
* @param paths list of paths
*/
class Paths(val paths: MutableList<Item>) {
constructor():
this(mutableListOf<Item>())
/**
* Empty collection of paths.
*/
constructor(): this(mutableListOf<Item>())
/**
* Add a [Path] to the list.
*
* @throws IllegalArgumentException if the given amount is smaller of equal to the paths trust amount.
*/
fun add(path: Path, amount: Int) {
require(amount <= path.amount) {
"Amount too small. TODO: Better error message"
@ -16,11 +28,18 @@ class Paths(val paths: MutableList<Item>) {
paths.add(Item(path, amount))
}
/**
* The summed trust amount of all paths in this collection.
*/
val amount: Int
get() {
return paths.sumOf { it.amount }
}
/**
* @param path path
* @param amount trust amount
*/
data class Item(val path: Path, val amount: Int) {
}

13
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/ReferenceTime.kt
View file

@ -6,11 +6,21 @@ package org.pgpainless.wot.dijkstra.sq
import java.util.*
/**
* Reference time for Web of Trust calculations.
*/
interface ReferenceTime {
/**
* Timestamp as [Date].
*/
val timestamp: Date
companion object {
/**
* Create a [ReferenceTime] with a timestamp that corresponds to the current time.
*/
@JvmStatic
fun now(): ReferenceTime {
val now = Date()
@ -20,6 +30,9 @@ interface ReferenceTime {
}
}
/**
* Create a [ReferenceTime] from the given [stamp] timestamp.
*/
@JvmStatic
fun timestamp(stamp: Date): ReferenceTime {
return object: ReferenceTime {

17
wot-dijkstra/src/main/kotlin/org/pgpainless/wot/dijkstra/sq/RegexSet.kt
View file

@ -6,25 +6,42 @@ package org.pgpainless.wot.dijkstra.sq
import java.util.regex.Pattern
/**
* Set of regular expressions.
*/
data class RegexSet(val regexStrings: Set<String>) {
companion object {
/**
* Create a [RegexSet] from the given [List] of RegEx strings.
*/
@JvmStatic
fun fromExpressionList(regexList: List<String>): RegexSet {
return RegexSet(regexList.toSet())
}
/**
* Create a [RegexSet] from a single RegEx string.
*/
@JvmStatic
fun fromExpression(regex: String): RegexSet {
return fromExpressionList(listOf(regex))
}
/**
* Create a wildcard RegEx (empty list of RegEx strings).
*/
@JvmStatic
fun wildcard(): RegexSet {
return fromExpressionList(listOf())
}
}
/**
* Return true if the given [string] matches the [RegexSet].
* That is if at least one RegEx in the set matches the [string], or if the set represents a wildcard.
*/
fun matches(string: String): Boolean {
if (regexStrings.isEmpty()) {
return true