import fs from 'fs'
import { execFile } from 'child_process'
import get from 'lodash-es/get.js'
import isFunction from 'lodash-es/isFunction.js'
let letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')
let units = {
'': 1,
'K': 1024,
'M': 1024 * 1024,
'G': 1024 * 1024 * 1024,
'T': 1024 * 1024 * 1024 * 1024,
}
//df -kP資料列依序為: 檔案系統, 總量, 已用, 可用, 使用率, 掛載點; 以中間數字欄錨定, 數值可為負(BSD可用量)或'-'(未知)
//首欄可為空字串(以空字串為來源之掛載, GNU df印成補滿空白之空欄), 首欄與末欄可含換行以外任意字元(含CR、U+2028、U+2029), -kP下GNU與BusyBox皆不換行
let regRow = /^(.*?)\s+(-?\d+|-)\s+(-?\d+|-)\s+(-?\d+|-)\s+(\d+%|-)\s+(\/.*)$/s
//df標頭之單位, 例如'1024-blocks'、'512-blocks'、'1K-blocks', 譯為他國語言時仍保留'數字-'格式
let regUnit = /(\d+)([KMGT]?)B?-/i
//進行中之查詢, 依查詢函數分開保存(測試注入之函數各自獨立), 同一查詢對象同時只保留一個進行中請求, 避免卡住的請求(如斷線之網路磁碟)隨輪詢累積佔用執行緒池
//僅限制同一對象不重複, 不限制總數: 同時無回應之磁碟代號數達UV_THREADPOOL_SIZE(預設4)時, 單次呼叫即會佔滿執行緒池直至系統放棄
let inFlights = new WeakMap()
//df逾時以SIGKILL中止後通常數十ms內結束, 逾期超過此寬限仍未結束者視為卡住(如FUSE請求已送至使用者空間, SIGKILL後仍不可中斷地等待)
let dfStuckGrace = 1000
function toNumber(v) {
let n = Number(v) //statfs可能回傳number或bigint
return Number.isFinite(n) ? n : 0
}
function toTimeout(v, def) {
let n = Number(v)
if (!Number.isFinite(n) || n <= 0) {
return def
}
return Math.min(2147483647, Math.max(1, Math.round(n))) //execFile之timeout須為整數; Node計時器上限2147483647ms, 超過會被改為1ms而立即逾時
}
function createTimeoutError(msg) {
let err = new Error(msg)
err.timeout = true
return err
}
function shareInFlight(fn, key, start) {
let m = inFlights.get(fn)
if (!m) {
m = new Map()
inFlights.set(fn, m)
}
let rec = m.get(key)
if (!rec) {
rec = {
pm: Promise.resolve().then(start),
t: performance.now(), //單調時鐘, 不受系統時間校正或手動調整影響
}
m.set(key, rec)
let clear = () => {
if (m.get(key) === rec) {
m.delete(key)
}
}
rec.pm.then(clear, clear)
}
return rec
}
function waitInFlight(rec, ms, msg) {
//逾時自請求發出起算(含執行緒池排隊時間), 已逾時仍未結束之請求不再等待亦不重發
let remain = ms - (performance.now() - rec.t)
if (remain <= 0) {
return Promise.reject(createTimeoutError(msg))
}
let t = null
let pmTimeout = new Promise((resolve, reject) => {
t = setTimeout(() => {
reject(createTimeoutError(msg))
}, remain)
})
return Promise.race([rec.pm, pmTimeout])
.finally(() => {
clearTimeout(t)
})
}
async function getDisksByStatfs(statfs, timeoutDrive) {
if (!isFunction(statfs)) {
throw new Error('fs.promises.statfs is not available, requires Node.js >= 18.15.0')
}
//各代號之結果依代號順序保存, 使錯誤訊息不受完成先後影響
let timeouts = []
let fails = []
let rs = await Promise.all(letters.map(async (c, k) => {
let name = `${c}:`
let root = `${name}\\` //須帶根目錄斜線, 僅給'C:'會依該碟之目前目錄解析
try {
let rec = shareInFlight(statfs, root, () => statfs(root))
let s = await waitInFlight(rec, timeoutDrive, `statfs ${root} timeout`)
let bsize = toNumber(s.bsize)
let total = toNumber(s.blocks) * bsize
if (total <= 0) {
return null
}
let free = Math.max(0, toNumber(s.bavail) * bsize)
return {
name,
display: '', //statfs無磁碟描述可用, 且不另啟外部程式取得
total,
free,
used: Math.max(0, total - free), //同舊版以總量減可用; 有配額時blocks與bavail皆為呼叫者範圍, bfree則為整卷, 不可混用
}
}
catch (err) {
//磁碟代號不存在、無媒體、無權限、逾時或前次查詢尚未結束者皆略過
if (err.timeout) {
timeouts[k] = name
}
else if (get(err, 'code') !== 'ENOENT') {
fails[k] = `${name} ${get(err, 'code') || 'error'}`
}
return null
}
}))
rs = rs.filter((r) => r !== null)
timeouts = timeouts.filter((v) => v)
fails = fails.filter((v) => v)
//全數失敗且有逾時或代號不存在以外之錯誤(如Node權限模型未授權讀取磁碟根目錄)者視為量測失敗, 不以空陣列冒充無磁碟; 僅全部代號皆不存在時回傳空陣列
if (rs.length === 0 && timeouts.length > 0) {
throw new Error(`statfs timeout: ${timeouts.join(', ')}`)
}
if (rs.length === 0 && fails.length > 0) {
throw new Error(`statfs failed: ${fails.join(', ')}`)
}
return rs
}
function runDf(execFileFn, timeout) {
//進行中之df依逾時值分開共用: df子程序以發起者之逾時中止, 若與不同逾時之呼叫者共用, 較長逾時者會於較短者之期限被一併中止
let key = `df:${timeout}`
let m = inFlights.get(execFileFn)
if (m && !m.has(key)) {
//其他逾時值之df逾期超過寬限仍未結束時視為卡住, 不論逾時值皆不再啟動新df, 避免卡住之df隨不同逾時值累積
let now = performance.now()
for (let [k, r] of m) {
if (k.startsWith('df:') && now - r.t >= Number(k.slice(3)) + dfStuckGrace) {
return Promise.reject(createTimeoutError('df timeout'))
}
}
}
let rec = shareInFlight(execFileFn, key, () => {
return new Promise((resolve) => {
let env = { ...process.env }
delete env.POSIXLY_CORRECT //BusyBox於此環境變數存在時忽略-k改以512為單位
execFileFn('df', ['-kP'], {
env,
timeout,
killSignal: 'SIGKILL',
windowsHide: true,
maxBuffer: 10 * 1024 * 1024,
}, (err, stdout, stderr) => {
resolve({
err,
stdout: String(stdout || ''),
stderr: String(stderr || ''),
})
})
})
})
return waitInFlight(rec, timeout, 'df timeout')
}
function parseDf(stdout) {
let lines = String(stdout).split(/\r?\n/).filter((line) => line.trim() !== '')
let unit = 1024
let rs = []
lines.forEach((line, k) => {
let m = line.match(regRow)
if (!m) {
//首列為標頭, 由標頭取得單位, 取不到時維持1024
if (k === 0) {
let mu = line.match(regUnit)
if (mu) {
let u = Number(mu[1]) * units[mu[2].toUpperCase()]
if (u > 0) {
unit = u
}
}
}
return
}
let [, display, sTotal, sUsed, sFree, sPct, name] = m
if (sTotal === '-' || sUsed === '-' || sFree === '-') {
return //數值未知
}
if (sUsed === '-1' && sPct === '100%') {
return //數值未知: illumos/Solaris df於可用量未知時已用欄印-1且使用率固定印100%
}
let total = Number(sTotal) * unit
if (!(total > 0)) {
return //容量為0之偽檔案系統(如macOS之map auto_home)略過
}
rs.push({
name,
display,
total,
free: Math.max(0, Number(sFree) * unit), //BSD磁碟用量超過保留區時可用量為負
used: Math.max(0, Number(sUsed) * unit), //GNU df於可用區塊多於總量時已用量為負
})
})
return rs
}
async function getDisksByDf(execFileFn, timeout) {
let r = await runDf(execFileFn, timeout)
//df被訊號終止、被殺(逾時或輸出超過maxBuffer)或無法啟動時stdout不完整, 一律視為失敗; 僅正常結束之數字離開碼(如部分掛載點無法讀取)才採用已輸出之列
if (r.err && !(typeof r.err.code === 'number' && !r.err.killed && !r.err.signal)) {
throw r.err
}
//以解析出至少1列判定成功
let rs = parseDf(r.stdout)
if (rs.length === 0) {
if (r.err) {
throw r.err
}
throw new Error(`df returned no disk rows${r.stderr.trim() ? `: ${r.stderr.trim()}` : ''}`)
}
return rs
}
/**
* 取得各磁碟容量資訊,Windows以fs.statfs逐一查詢A:至Z:磁碟代號(需Node.js>=18.15.0),其他平台以df -kP取得,皆不依賴wmic
*
* Windows只列出可查得容量之磁碟代號,無媒體之光碟機等會略過;statfs無磁碟類型資訊,故卸除式、網路磁碟等可查得者亦會列出。
* 容量為0之偽檔案系統一律略過。同一磁碟代號或df同時只保留一個進行中請求,同時之呼叫共用其結果,逾時未結束者後續呼叫直接略過不重發;各呼叫者依自身逾時等待,df另依逾時值分開以免被較短逾時之發起者一併中止,但任一df逾期超過1秒仍未結束(視為卡住)時,不論逾時值皆不再啟動新df。
* 全部代號皆不存在時回傳空陣列;全部失敗且有逾時或其他錯誤時reject,df執行失敗或解析不出任何一列時亦reject。
*
* 限制:
* 1. Windows之statfs經libuv執行緒池執行且無法取消,timeoutDrive含排隊時間;每個無回應之磁碟代號(如伺服器不可達之網路磁碟,實測約21秒後系統才放棄)佔用一條執行緒至系統放棄,同時無回應者達UV_THREADPOOL_SIZE(預設4)時,宿主程序之非同步fs、dns、crypto、zlib皆須等待,可於啟動Node前以環境變數調高UV_THREADPOOL_SIZE。
* 2. Windows下Node.js<24.16(含18.x、20.x、22.x、25.x)之statfs以32位元回傳配置單位數,配置單位數超過4294967295之磁碟(如以1KiB為單位、大於4TiB之Samba/NAS網路磁碟,或4KiB叢集、大於16TiB之ReFS)容量會被截斷;NTFS磁碟不受影響。
* 3. 非Windows平台之df僅於正常結束(含部分掛載點無法讀取之非0離開碼)時採用其輸出,被逾時中止或輸出超過10MB時視為失敗。
*
* @param {Object} [opt={}] 輸入設定物件,預設{}
* @param {Integer} [opt.timeout=10000] 輸入非Windows平台執行df之逾時時間數字,單位ms,未給、非數值、非有限數(如'abc'、NaN、Infinity)或非正數時用預設,超過上限2147483647時以上限計,預設10000
* @param {Integer} [opt.timeoutDrive=3000] 輸入Windows平台查詢單一磁碟之逾時時間數字,單位ms,逾時之磁碟略過,未給、非數值、非有限數(如'abc'、NaN、Infinity)或非正數時用預設,超過上限2147483647時以上限計,預設3000
* @param {String} [opt.platform=process.platform] 輸入平台字串,供測試注入,預設process.platform
* @param {Function} [opt.statfs=fs.promises.statfs] 輸入查詢磁碟之函數,供測試注入,未給或給undefined時用預設,給null視為不可用,預設fs.promises.statfs
* @param {Function} [opt.execFile=child_process.execFile] 輸入執行外部程式之函數,供測試注入,預設child_process.execFile
* @returns {Promise} 回傳Promise,resolve回傳磁碟資訊物件陣列,各物件含name(Windows為磁碟代號如'C:',其他平台為掛載點)、display(Windows為空字串,其他平台為df之檔案系統名稱)、total、free、used(單位皆為byte),reject回傳錯誤訊息
* @example
*
* import getDisksInfo from './src/getDisksInfo.mjs'
*
* let r = await getDisksInfo()
* console.log(r)
* // => [
* // {
* // name: 'C:',
* // display: '',
* // total: 204936835072,
* // free: 34902945792,
* // used: 170033889280
* // }
* // ]
*
*/
async function getDisksInfo(opt = {}) {
//platform
let platform = get(opt, 'platform')
if (!platform) {
platform = process.platform
}
//timeout, timeoutDrive
let timeout = toTimeout(get(opt, 'timeout'), 10000)
let timeoutDrive = toTimeout(get(opt, 'timeoutDrive'), 3000)
//win32
if (platform === 'win32') {
let statfs = get(opt, 'statfs')
if (statfs === undefined) {
statfs = get(fs, 'promises.statfs') //未給或給undefined皆用預設, 測試以null模擬不可用
}
return getDisksByStatfs(statfs, timeoutDrive)
}
//execFileFn
let execFileFn = get(opt, 'execFile')
if (!isFunction(execFileFn)) {
execFileFn = execFile
}
return getDisksByDf(execFileFn, timeout)
}
export default getDisksInfo