FileBinary
Class: FileBinary<T>
Defined in: fs/src/filebinary.service.ts:99
FileBinary handles the storage of binary on a hard drive
The structure used for now is /folder/{hash}/data /folder/{hash}/{model}{attribute}{uuid} usage markers /folder/{hash}/proof_{challenge} proof of possession, written by the service on upload
Before 4.0.0-beta.5 the proof was _{challenge} and the challenge was sent to clients: those markers are ignored
(a leaked value attaches nothing), the content is uploaded once more to get a proof_ marker.
It takes one parameter folder: "path"
See Binary the general interface
Webda Modda
Extends
CloudBinary<T>
Type Parameters
T
T extends FileBinaryParameters = FileBinaryParameters
Constructors
Constructor
new FileBinary<
T>(name,params):FileBinary<T>
Defined in: core/lib/services/service.d.ts:72
Service
Parameters
name
string
The name of the service
params
T
The parameters block define in the configuration file
Returns
FileBinary<T>
Inherited from
CloudBinary<T>.constructor
Properties
_compiledCapabilities
protected_compiledCapabilities:Record<string,any>
Defined in: core/lib/services/iservice.d.ts:39
Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.
Populated during Service.resolve by reading the service's entry in
webda.module.json. Each key is a capability name (e.g., "request-filter"),
and the value is an empty object {} by default. Override getCapabilities
to provide capability-specific configuration or to conditionally disable capabilities.
See
getCapabilities
Inherited from
FileQueue._compiledCapabilities
_lowercaseMaps
_lowercaseMaps:
any
Defined in: core/lib/services/binary.service.d.ts:689
Inherited from
CloudBinary._lowercaseMaps
[WEBDA_EVENTS]
[WEBDA_EVENTS]:
BinaryEvents
Defined in: core/lib/services/service.d.ts:50
Set the Webda events here
Inherited from
CloudBinary.[WEBDA_EVENTS]
cryptoService
cryptoService:
CryptoService
Defined in: fs/src/filebinary.service.ts:104
Used for hmac
logger
protectedlogger:Logger
Defined in: core/lib/services/service.d.ts:59
Logger with class context
Inherited from
metrics
metrics:
object
Defined in: core/lib/services/binary.service.d.ts:690
Get metrics
delete
delete:
Counter
download
download:
Counter
metadataUpdate
metadataUpdate:
Counter
upload
upload:
Counter
Inherited from
CloudBinary.metrics
name
readonlyname:string
Defined in: core/lib/services/iservice.d.ts:19
Inherited from
parameters
readonlyparameters:T
Defined in: core/lib/services/iservice.d.ts:20
Inherited from
CloudBinary.parameters
createConfiguration?
staticoptionalcreateConfiguration?: (params) =>any
Defined in: core/lib/services/iservice.d.ts:24
Create configuration set by the application on load
Parameters
params
any
Returns
any
Inherited from
CloudBinary.createConfiguration
filterConfiguration?
staticoptionalfilterConfiguration?: (params) =>any
Defined in: core/lib/services/iservice.d.ts:28
Create configuration set by the application on load
Parameters
params
any
Returns
any
Inherited from
CloudBinary.filterConfiguration
Parameters
staticParameters: typeofServiceParameters
Defined in: core/lib/services/service.d.ts:46
Service parameters
Inherited from
CloudBinary.Parameters
Methods
___cleanData()
___cleanData():
Promise<void>
Defined in: fs/src/filebinary.service.ts:568
Clean all data
Returns
Promise<void>
Overrides
CloudBinary.___cleanData
__clean()
abstract__clean():Promise<void>
Defined in: core/lib/services/service.d.ts:215
Clean the service data, can only be used in test mode
Returns
Promise<void>
Inherited from
CloudBinary.__clean
_cleanHash()
_cleanHash(
hash):Promise<void>
Defined in: fs/src/filebinary.service.ts:443
Delete any usage marker and hash
Parameters
hash
string
the content hash to clean
Returns
Promise<void>
_cleanUsage()
_cleanUsage(
hash,uuid,attribute?):Promise<void>
Defined in: fs/src/filebinary.service.ts:456
Parameters
hash
string
uuid
string
attribute?
string
Returns
Promise<void>
Overrides
CloudBinary._cleanUsage
_get()
_get(
info):Promise<Readable>
Defined in: fs/src/filebinary.service.ts:216
Parameters
info
BinaryMap
Returns
Promise<Readable>
Overrides
CloudBinary._get
_getKey()
_getKey(
hash,suffix?):string
Defined in: core/lib/services/cloudbinary.d.ts:34
Return the S3 key
Parameters
hash
string
the hash value
suffix?
string
the suffix to append
Returns
string
the result string
Inherited from
CloudBinary._getKey
_getPath()
_getPath(
hash,postfix?):string
Defined in: fs/src/filebinary.service.ts:249
Get storage path for a hash
Parameters
hash
string
the content hash
postfix?
string = undefined
optional path suffix
Returns
string
the filesystem path
_store()
_store(
file,object,attribute):Promise<void>
Defined in: fs/src/filebinary.service.ts:527
Write a binary file's stream to the local filesystem under its content-hash directory.
Parameters
file
BinaryFile
the binary file to store
object
CoreModel
the model instance
attribute
string
the binary attribute name
Returns
Promise<void>
_touch()
_touch(
filePath,mode?):void
Defined in: fs/src/filebinary.service.ts:262
Create a file if it does not already exist, using the given permission mode.
Parameters
filePath
any
path of the file to create
mode?
number = 0o600
file permission mode
Returns
void
addListener()
addListener<
Key>(eventName,listener):this
Defined in: core/lib/events/asynceventemitter.d.ts:80
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName
Key
the event name
listener
(event) => void | Promise<void>
the event listener
Returns
this
this for chaining
See
EventEmitter.addListener
Inherited from
CloudBinary.addListener
addRoute()
protectedaddRoute(url,methods,executer,openapi?,override?):void
Defined in: core/lib/services/service.d.ts:177
Add a route dynamicaly
Parameters
url
string
of the route can contains dynamic part like {uuid}
methods
HttpMethodType[]
the HTTP methods
executer
Function
Method to execute for this route
openapi?
OpenAPIWebdaDefinition
the OpenAPI specification
override?
boolean
whether to override existing
Returns
void
Inherited from
CloudBinary.addRoute
attach()
protectedattach(object,target,hashes):Promise<void>
Defined in: fs/src/filebinary.service.ts:328
Attach a stored binary to an object: usage marker, then the object's binary attribute
Parameters
object
CoreModel
the model instance
target
the object attribute and the announced file information
hashes
the stored content
challenge
string
its challenge
hash
string
its hash
Returns
Promise<void>
authorizeClientEvent()
authorizeClientEvent(
_event,_context):boolean
Defined in: core/lib/services/service.d.ts:153
Authorize a public event subscription
Parameters
_event
string
the event name
_context
OperationContext
the execution context
Returns
boolean
true if the condition is met
Inherited from
CloudBinary.authorizeClientEvent
cascadeDelete()
cascadeDelete(
info,uuid):Promise<void>
Defined in: fs/src/filebinary.service.ts:516
Parameters
info
BinaryMap
uuid
string
Returns
Promise<void>
Overrides
CloudBinary.cascadeDelete
challenge()
challenge(
hash,challenge):boolean
Defined in: fs/src/filebinary.service.ts:495
Verify that a binary with the given hash exists and carries the proof marker of the challenge, written by the service when the content was uploaded
Parameters
hash
any
the content hash
challenge
any
the challenge string
Returns
boolean
true if the proof marker exists
checkMap()
protectedcheckMap(object,property):void
Defined in: core/lib/services/binary.service.d.ts:790
Check if a map is defined
Parameters
object
Model
the target object
property
string
the property name
Returns
void
Inherited from
CloudBinary.checkMap
computeParameters()
computeParameters():
void
Defined in: fs/src/filebinary.service.ts:118
Create the storage folder if needed
Returns
void
Overrides
CloudBinary.computeParameters
delete()
delete(
object,property,index?):Promise<void>
Defined in: fs/src/filebinary.service.ts:472
Parameters
object
CoreModelWithBinary
property
string
index?
number
Returns
Promise<void>
Overrides
CloudBinary.delete
deleteSuccess()
deleteSuccess(
object,property,index?):Promise<void>
Defined in: core/lib/services/binary.service.d.ts:815
Parameters
object
CoreModelWithBinary
the target object
property
string
the property name
index?
number
the index
Returns
Promise<void>
the result
Inherited from
CloudBinary.deleteSuccess
downloadBinaryLink()
downloadBinaryLink(
ctx):Promise<void>
Defined in: fs/src/filebinary.service.ts:189
Download a binary with a signed download token (issued by the download behavior action, after the model's
permission check)
Parameters
ctx
WebContext<any, any, { hash: string; }>
the web context
Returns
Promise<void>
downloadTo()
downloadTo(
info,filename):Promise<void>
Defined in: core/lib/services/binary.service.d.ts:768
Download a binary to a file
Parameters
info
BinaryMap
The reference stored in your target object
filename
any
the filename
Returns
Promise<void>
Inherited from
CloudBinary.downloadTo
emit()
emit<
Key>(event,data):Promise<void>
Defined in: core/lib/services/service.d.ts:204
Emit the event with data and wait for Promise to finish if listener returned a Promise
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
event
Key
the event name
data
BinaryEvents[Key]
the data to process
Returns
Promise<void>
Inherited from
CloudBinary.emit
get()
get(
info):Promise<Readable>
Defined in: core/lib/services/binary.service.d.ts:760
Get a binary
Parameters
info
BinaryMap
The reference stored in your target object
Returns
Promise<Readable>
the result
Emits
'binaryGet'
Inherited from
CloudBinary.get
getCapabilities()
getCapabilities():
Record<string,any>
Defined in: core/lib/services/iservice.d.ts:61
Return the capabilities of this service.
By default returns capabilities detected at compile-time from
Returns
Record<string, any>
the result
Webda Capability-tagged
interfaces in webda.module.json.
Override to disable capabilities based on configuration:
getCapabilities() {
const caps = super.getCapabilities();
if (!this.parameters.enabled) delete caps["request-filter"];
return caps;
}
Inherited from
CloudBinary.getCapabilities
getClientEvents()
getClientEvents():
string[]
Defined in: core/lib/services/service.d.ts:144
Return the events that an external system can subscribe to
Returns
string[]
the list of results
Inherited from
CloudBinary.getClientEvents
getFile()
getFile(
req):Promise<BinaryFile<{ }>>
Defined in: core/lib/services/binary.service.d.ts:821
Get file either from multipart post or raw
Parameters
req
IOperationContext
the request
Returns
Promise<BinaryFile<{ }>>
the result
Inherited from
CloudBinary.getFile
getMaxListeners()
getMaxListeners():
number
Defined in: core/lib/events/asynceventemitter.d.ts:84
Returns
number
Inherited from
CloudBinary.getMaxListeners
getMetric()
getMetric<
T>(type,configuration):T
Defined in: core/lib/services/service.d.ts:138
Add service name label
Type Parameters
T
T = Counter<string> | Gauge<string> | Histogram<string>
Parameters
type
CustomConstructor<T, [MetricConfiguration<T>]>
the type to look up
configuration
MetricConfiguration<T>
the configuration
Returns
T
the result
Inherited from
CloudBinary.getMetric
getName()
getName():
string
Defined in: core/lib/services/service.d.ts:209
Get service name
Returns
string
the result string
Inherited from
CloudBinary.getName
getOpenApiReplacements()
getOpenApiReplacements():
any
Defined in: core/lib/services/service.d.ts:182
Return variables for replacement in openapi
Returns
any
the result
Inherited from
CloudBinary.getOpenApiReplacements
getOperationId()
getOperationId(
id):string
Defined in: core/lib/services/service.d.ts:167
If undefined is returned it cancel the operation registration
Parameters
id
string
the identifier
Returns
string
the result
Inherited from
CloudBinary.getOperationId
getOperationName()
protectedgetOperationName():string
Defined in: core/lib/services/binary.service.d.ts:826
Return the name of the service for OpenAPI
Returns
string
the result string
Inherited from
CloudBinary.getOperationName
getParameters()
getParameters():
T
Defined in: core/lib/services/service.d.ts:82
Get the service parameters
Returns
T
the result
Inherited from
CloudBinary.getParameters
getPutUrl()
getPutUrl(
ctx,hash?,target?):Promise<string>
Defined in: fs/src/filebinary.service.ts:292
Get put URL
Parameters
ctx
OperationContext<BinaryFile<{ }>>
the operation context
hash?
string
the content hash (read from the input when not given)
target?
what the upload attaches once the content is stored and verified
Returns
Promise<string>
the upload URL
getRedirectUrlFromObject()
getRedirectUrlFromObject(
binaryMap,context,expires?):Promise<string>
Defined in: core/lib/services/cloudbinary.d.ts:27
Get a UrlFromObject
Parameters
binaryMap
any
the binary map definition
context
any
the execution context
expires?
number
the expiration time
Returns
Promise<string>
the result
Inherited from
CloudBinary.getRedirectUrlFromObject
getService()
getService<
T>(name):ServicesMap[T]
Defined in: core/lib/services/service.d.ts:131
Get a service by name
Type Parameters
T
T extends keyof ServicesMap
Parameters
name
T
the name to use
Returns
ServicesMap[T]
the result map
Deprecated
Use useService, might reconsider
Inherited from
CloudBinary.getService
getSignedUrlFromMap()
getSignedUrlFromMap(
map,expires,context):Promise<string>
Defined in: fs/src/filebinary.service.ts:232
Get signed url to download an element
Parameters
map
BinaryMap
the binary map
expires
number
expiration time in seconds
context
WebContext
the web context
Returns
Promise<string>
the signed download URL
Overrides
CloudBinary.getSignedUrlFromMap
getState()
getState():
ServiceStates
Defined in: core/lib/services/service.d.ts:55
Get the current state
Returns
ServiceStates
the result
Inherited from
CloudBinary.getState
getToken()
getToken(
hash,method,expiresIn?,target?):Promise<string>
Defined in: fs/src/filebinary.service.ts:280
Get token for action
Parameters
hash
string
the content hash
method
"PUT" | "GET"
HTTP method (PUT or GET)
expiresIn?
number = 60
token TTL in seconds
target?
for an upload token, what to attach once the content is stored and verified
Returns
Promise<string>
the signed JWT token
getUrl()
getUrl(
url,_methods):string
Defined in: core/lib/services/service.d.ts:161
Return the full path url based on parameters
Parameters
url
string
relative url to service
_methods
HttpMethodType[]
in case we need filtering (like Store)
Returns
string
absolute url or undefined if need to skip the Route
Inherited from
CloudBinary.getUrl
getUsageCount()
getUsageCount(
hash):Promise<number>
Defined in: fs/src/filebinary.service.ts:434
Parameters
hash
string
Returns
Promise<number>
Overrides
CloudBinary.getUsageCount
handleBinary()
handleBinary(
modelName,attribute):-1|0|1|2
Defined in: core/lib/services/binary.service.d.ts:715
Define if binary is managed by the store
Parameters
modelName
string
the model name
attribute
string
the attribute name
Returns
-1 | 0 | 1 | 2
-1 if not managed, 0 if managed but by default, 1 if managed and in the map, 2 if explicit with attribute and model
Inherited from
CloudBinary.handleBinary
init()
init():
Promise<FileBinary<T>>
Defined in: fs/src/filebinary.service.ts:133
Register download/upload routes if a public URL is configured.
Routes depend on the runtime parameters.url + content hash, so they're
registered programmatically rather than via @Route.
Returns
Promise<FileBinary<T>>
this for chaining
Overrides
CloudBinary.init
initMetrics()
initMetrics():
void
Defined in: core/lib/services/binary.service.d.ts:699
Returns
void
Inherited from
CloudBinary.initMetrics
initOperations()
initOperations():
void
Defined in: core/lib/services/service.d.ts:186
Init the operations from
Returns
void
Operation
decorators on this service
Inherited from
CloudBinary.initOperations
listeners()
listeners(
eventName):Function[]
Defined in: core/lib/events/asynceventemitter.d.ts:139
Get all listeners for an event
Parameters
eventName
keyof BinaryEvents
the event name
Returns
Function[]
the list of results
Inherited from
CloudBinary.listeners
loadCapabilities()
protectedloadCapabilities():void
Defined in: core/lib/services/service.d.ts:120
Load capabilities from webda.module.json metadata into _compiledCapabilities.
Called during resolve after dependency injection. Reads the service's
type name from parameters, looks it up in the application's module metadata
(moddas or beans section), and populates _compiledCapabilities with an
empty object for each declared capability name.
Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).
Returns
void
Example
// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }
See
getCapabilities
Inherited from
CloudBinary.loadCapabilities
loadParameters()
loadParameters(
params):T
Defined in: fs/src/filebinary.service.ts:111
Load parameters
Parameters
params
any
raw parameter values
Returns
T
the loaded parameters
log()
log(
level, ...args):void
Defined in: core/lib/services/service.d.ts:226
Parameters
level
WorkerLogLevel
to log
args
...any[]
additional arguments
Returns
void
Inherited from
CloudBinary.log
newModel()
newModel(
obj):BinaryMap
Defined in: core/lib/services/binary.service.d.ts:775
Based on the raw Map init a BinaryMap
Parameters
obj
any
the target object
Returns
BinaryMap
the result map
Inherited from
CloudBinary.newModel
off()
off<
Key>(eventName,listener):this
Defined in: core/lib/events/asynceventemitter.d.ts:116
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName
Key
the event name
listener
(event) => void
the event listener
Returns
this
this for chaining
See
EventEmitter.off
Inherited from
CloudBinary.off
on()
on<
Key>(eventName,listener):this
Defined in: core/lib/events/asynceventemitter.d.ts:102
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName
Key
the event name
listener
(event) => void
the event listener
Returns
this
this for chaining
See
EventEmitter.once
Inherited from
CloudBinary.on
once()
once<
Key>(eventName,listener):this
Defined in: core/lib/events/asynceventemitter.d.ts:95
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName
Key
the event name
listener
(event) => void
the event listener
Returns
this
this for chaining
See
EventEmitter.once
Inherited from
CloudBinary.once
proofMarker()
protectedproofMarker(challenge):string
Defined in: fs/src/filebinary.service.ts:483
Name of the proof marker of a challenge (legacy _<challenge> markers are not proofs)
Parameters
challenge
string
the challenge
Returns
string
the marker file name
putRedirectUrl()
putRedirectUrl(
object,attribute,info?,context?):Promise<{method:string;url:string; }>
Defined in: fs/src/filebinary.service.ts:357
Challenge: the client announces {hash, challenge, ...}; the challenge is the md5 of "WEBDA" + the content,
so a matching one proves possession of an already stored binary, which is then attached without upload
(undefined). Otherwise the upload URL is returned and nothing is attached yet: the upload stores the
content, verifies it against the announced hash and attaches it then (storeBinary). A visible hash
alone therefore never gives access to another object's binary.
Parameters
object
CoreModel
the model instance
attribute
string
the binary attribute name
info?
BinaryFile
optional binary file info
context?
OperationContext<BinaryFile<{ }>>
the operation context
Returns
Promise<{ method: string; url: string; }>
the upload URL and method, or undefined when the binary is attached
Overrides
CloudBinary.putRedirectUrl
removeAllListeners()
removeAllListeners<
Key>(eventName?):this
Defined in: core/lib/events/asynceventemitter.d.ts:122
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName?
Key
the event name
Returns
this
this for chaining
See
EventEmitter.removeAllListeners
Inherited from
CloudBinary.removeAllListeners
removeListener()
removeListener<
Key>(eventName,listener):this
Defined in: core/lib/events/asynceventemitter.d.ts:109
Type Parameters
Key
Key extends keyof BinaryEvents
Parameters
eventName
Key
the event name
listener
(event) => void
the event listener
Returns
this
this for chaining
See
EventEmitter.removeListener
Inherited from
CloudBinary.removeListener
resolve()
resolve():
this
Defined in: core/lib/services/service.d.ts:98
Resolve parameters and load metadata. @Route-declared routes are scanned
and registered by Router.discoverRoutes(services) from Core.init()
once every service has resolved — nothing to do per-service here.
Returns
this
the result
Inherited from
CloudBinary.resolve
safeName()
protectedsafeName(part):string
Defined in: fs/src/filebinary.service.ts:307
Make a marker name part file-safe: the model identifier carries a /, and a natural key is client-chosen, so
anything but letters, digits, _, ., :, @ and - is replaced (a marker is a file inside the hash folder)
Parameters
part
string
the raw value
Returns
string
the safe name part
setMaxListeners()
setMaxListeners(
n):this
Defined in: core/lib/events/asynceventemitter.d.ts:88
Parameters
n
number
Returns
this
Inherited from
CloudBinary.setMaxListeners
stop()
stop():
Promise<void>
Defined in: core/lib/services/service.d.ts:86
Shutdown the current service if action need to be taken
Returns
Promise<void>
Inherited from
CloudBinary.stop
store()
store(
object,property,file):Promise<any>
Defined in: fs/src/filebinary.service.ts:549
Parameters
object
CoreModel
property
string
file
BinaryFile
Returns
Promise<any>
Overrides
CloudBinary.store
storeBinary()
storeBinary(
ctx):Promise<void>
Defined in: fs/src/filebinary.service.ts:386
Store the binary sent with an upload token, then attach it to the object the token names
Parameters
ctx
WebContext
the web context
Returns
Promise<void>
toJSON()
toJSON():
string
Defined in: core/lib/services/service.d.ts:191
Prevent service to be serialized
Returns
string
the result
Inherited from
CloudBinary.toJSON
toString()
toString():
string
Defined in: core/lib/services/service.d.ts:91
Return service representation
Returns
string
the result
Inherited from
CloudBinary.toString
uploadSuccess()
uploadSuccess(
object,property,fileInfo):Promise<void>
Defined in: core/lib/services/binary.service.d.ts:797
Ensure events are sent correctly after an upload and update the BinaryFileInfo in targetted object
Parameters
object
CoreModelWithBinary
the target object
property
string
the property name
fileInfo
BinaryFileInfo<{ }> | { toBinaryFileInfo: () => BinaryFileInfo; }
the file information
Returns
Promise<void>
Inherited from
CloudBinary.uploadSuccess
usageMarker()
protectedusageMarker(target):string
Defined in: fs/src/filebinary.service.ts:316
Usage marker of an object attribute in a hash folder: <model>_<attribute>_<uuid>, every part file-safe
Parameters
target
Pick<UploadTarget, "model" | "attribute" | "uuid">
the object attribute
Returns
string
the marker file name
usageMarkers()
protectedusageMarkers(hash):string[]
Defined in: fs/src/filebinary.service.ts:505
Usage markers of a hash folder: every file but the data and the proof markers (legacy _ ones included)
Parameters
hash
string
the content hash
Returns
string[]
the marker names
verifyMapAndStore()
protectedverifyMapAndStore(ctx):IStore
Defined in: core/lib/services/binary.service.d.ts:832
Based on the request parameter verify it match a known mapping
Parameters
ctx
IOperationContext
the operation context
Returns
IStore
the result
Inherited from
CloudBinary.verifyMapAndStore
streamToBuffer()
staticstreamToBuffer(stream):Promise<Buffer<ArrayBufferLike>>
Defined in: core/lib/services/binary.service.d.ts:782
Read a stream to a buffer
Parameters
stream
Readable
the stream
Returns
Promise<Buffer<ArrayBufferLike>>
the result
Inherited from
CloudBinary.streamToBuffer