Start9/start-os
2
0
Fork 0
mirror of https://github.com/Start9Labs/start-os.git synced 2026-04-04 22:39:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

add comments to everything potentially consumer facing

Browse Source
This commit is contained in:
Matt Hill
2026-02-21 20:40:45 -07:00
parent 31352a72c3
commit 804560d43c
39 changed files with 1463 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
sdk/base/lib/util/ip.ts
View File

@@ -1,3 +1,14 @@
/**
* Represents an IPv4 or IPv6 address as raw octets with arithmetic and comparison operations.
*
* IPv4 addresses have 4 octets, IPv6 addresses have 16 octets.
*
* @example
* ```ts
* const ip = IpAddress.parse("192.168.1.1")
* const next = ip.add(1) // 192.168.1.2
* ```
*/
export class IpAddress {
private renderedOctets: number[]
protected constructor(
@@ -6,6 +17,13 @@ export class IpAddress {
) {
this.renderedOctets = [...octets]
}
/**
* Parses an IP address string into an IpAddress instance.
* Supports both IPv4 dotted-decimal and IPv6 colon-hex notation (including `::` shorthand).
* @param address - The IP address string to parse
* @returns A new IpAddress instance
* @throws Error if the address format is invalid
*/
static parse(address: string): IpAddress {
let octets
if (address.includes(':')) {
@@ -39,6 +57,12 @@ export class IpAddress {
}
return new IpAddress(octets, address)
}
/**
* Creates an IpAddress from a raw octet array.
* @param octets - Array of 4 octets (IPv4) or 16 octets (IPv6), each 0-255
* @returns A new IpAddress instance
* @throws Error if the octet array length is not 4 or 16, or any octet exceeds 255
*/
static fromOctets(octets: number[]) {
if (octets.length == 4) {
if (octets.some((o) => o > 255)) {
@@ -66,15 +90,24 @@ export class IpAddress {
throw new Error('invalid ip address')
}
}
/** Returns true if this is an IPv4 address (4 octets). */
isIpv4(): boolean {
return this.octets.length === 4
}
/** Returns true if this is an IPv6 address (16 octets). */
isIpv6(): boolean {
return this.octets.length === 16
}
/** Returns true if this is a public IPv4 address (not in any private range). */
isPublic(): boolean {
return this.isIpv4() && !PRIVATE_IPV4_RANGES.some((r) => r.contains(this))
}
/**
* Returns a new IpAddress incremented by `n`.
* @param n - The integer amount to add (fractional part is truncated)
* @returns A new IpAddress with the result
* @throws Error on overflow
*/
add(n: number): IpAddress {
let octets = [...this.octets]
n = Math.floor(n)
@@ -92,6 +125,12 @@ export class IpAddress {
}
return IpAddress.fromOctets(octets)
}
/**
* Returns a new IpAddress decremented by `n`.
* @param n - The integer amount to subtract (fractional part is truncated)
* @returns A new IpAddress with the result
* @throws Error on underflow
*/
sub(n: number): IpAddress {
let octets = [...this.octets]
n = Math.floor(n)
@@ -109,6 +148,11 @@ export class IpAddress {
}
return IpAddress.fromOctets(octets)
}
/**
* Compares this address to another, returning -1, 0, or 1.
* @param other - An IpAddress instance or string to compare against
* @returns -1 if this < other, 0 if equal, 1 if this > other
*/
cmp(other: string | IpAddress): -1 | 0 | 1 {
if (typeof other === 'string') other = IpAddress.parse(other)
const len = Math.max(this.octets.length, other.octets.length)
@@ -123,6 +167,7 @@ export class IpAddress {
}
return 0
}
/** The string representation of this IP address (e.g. `"192.168.1.1"` or `"::1"`). Cached and recomputed only when octets change. */
get address(): string {
if (
this.renderedOctets.length === this.octets.length &&
@@ -160,6 +205,17 @@ export class IpAddress {
}
}
/**
* Represents an IP network (CIDR notation) combining an IP address with a prefix length.
* Extends IpAddress with network-specific operations like containment checks and broadcast calculation.
*
* @example
* ```ts
* const net = IpNet.parse("192.168.1.0/24")
* net.contains("192.168.1.100") // true
* net.broadcast() // 192.168.1.255
* ```
*/
export class IpNet extends IpAddress {
private constructor(
octets: number[],
@@ -168,18 +224,35 @@ export class IpNet extends IpAddress {
) {
super(octets, address)
}
/**
* Creates an IpNet from an IpAddress and prefix length.
* @param ip - The base IP address
* @param prefix - The CIDR prefix length (0-32 for IPv4, 0-128 for IPv6)
* @returns A new IpNet instance
* @throws Error if prefix exceeds the address bit length
*/
static fromIpPrefix(ip: IpAddress, prefix: number): IpNet {
if (prefix > ip.octets.length * 8) {
throw new Error('invalid prefix')
}
return new IpNet(ip.octets, prefix, ip.address)
}
/**
* Parses a CIDR notation string (e.g. `"192.168.1.0/24"`) into an IpNet.
* @param ipnet - The CIDR string to parse
* @returns A new IpNet instance
*/
static parse(ipnet: string): IpNet {
const [address, prefixStr] = ipnet.split('/', 2)
const ip = IpAddress.parse(address)
const prefix = Number(prefixStr)
return IpNet.fromIpPrefix(ip, prefix)
}
/**
* Checks whether this network contains the given address or subnet.
* @param address - An IP address or subnet (string, IpAddress, or IpNet)
* @returns True if the address falls within this network's range
*/
contains(address: string | IpAddress | IpNet): boolean {
if (typeof address === 'string') address = IpAddress.parse(address)
if (address instanceof IpNet && address.prefix < this.prefix) return false
@@ -197,6 +270,7 @@ export class IpNet extends IpAddress {
const mask = 255 ^ (255 >> prefix)
return (this.octets[idx] & mask) === (address.octets[idx] & mask)
}
/** Returns the network address (all host bits zeroed) for this subnet. */
zero(): IpAddress {
let octets: number[] = []
let prefix = this.prefix
@@ -213,6 +287,7 @@ export class IpNet extends IpAddress {
return IpAddress.fromOctets(octets)
}
/** Returns the broadcast address (all host bits set to 1) for this subnet. */
broadcast(): IpAddress {
let octets: number[] = []
let prefix = this.prefix
@@ -229,11 +304,13 @@ export class IpNet extends IpAddress {
return IpAddress.fromOctets(octets)
}
/** The CIDR notation string for this network (e.g. `"192.168.1.0/24"`). */
get ipnet() {
return `${this.address}/${this.prefix}`
}
}
/** All private IPv4 ranges: loopback (127.0.0.0/8), Class A (10.0.0.0/8), Class B (172.16.0.0/12), Class C (192.168.0.0/16). */
export const PRIVATE_IPV4_RANGES = [
IpNet.parse('127.0.0.0/8'),
IpNet.parse('10.0.0.0/8'),
@@ -241,8 +318,12 @@ export const PRIVATE_IPV4_RANGES = [
IpNet.parse('192.168.0.0/16'),
]
/** IPv4 loopback network (127.0.0.0/8). */
export const IPV4_LOOPBACK = IpNet.parse('127.0.0.0/8')
/** IPv6 loopback address (::1/128). */
export const IPV6_LOOPBACK = IpNet.parse('::1/128')
/** IPv6 link-local network (fe80::/10). */
export const IPV6_LINK_LOCAL = IpNet.parse('fe80::/10')
/** Carrier-Grade NAT (CGNAT) address range (100.64.0.0/10), per RFC 6598. */
export const CGNAT = IpNet.parse('100.64.0.0/10')