Skip to main content

BinaryService

@webda/core

Abstract Class: BinaryService<T, E>

Defined in: packages/core/src/services/binary.service.ts:1361

This is an abstract service to represent a storage of files The binary allow you to expose this service as HTTP

It supports two modes:

  • attached to a CoreModel (attach, detach, reattach)
  • pure storage with no managed id (read, write, delete)

As we have deduplication builtin you can get some stats

  • getUsageCount(hash)
  • getUsageCountForRaw()
  • getUsageCountForMap()

The Binary storage should store only once a binary and reference every object that are used by this binary, so it can be cleaned.

See​

  • FileBinary
  • S3Binary

Exports​

Webda Modda​

Binary

Extends​

Extended by​

Type Parameters​

T​

T extends BinaryParameters = BinaryParameters

E​

E extends BinaryEvents = BinaryEvents

Implements​

Constructors​

Constructor​

new BinaryService<T, E>(name, params): BinaryService<T, E>

Defined in: packages/core/src/services/service.ts:205

Create a new Service instance

Service

Parameters​

name​

string

The name of the service

params​

T

The parameters block define in the configuration file

Returns​

BinaryService<T, E>

Inherited from​

Service.constructor

Properties​

_compiledCapabilities​

protected _compiledCapabilities: Record<string, any> = {}

Defined in: packages/core/src/services/iservice.ts:61

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​

Service._compiledCapabilities

_lowercaseMaps​

_lowercaseMaps: any

Defined in: packages/core/src/services/binary.service.ts:1371

Lowercase maps

[WEBDA_EVENTS]​

[WEBDA_EVENTS]: E

Defined in: packages/core/src/services/service.ts:179

Set the Webda events here

Inherited from​

Service.[WEBDA_EVENTS]

hookedModels​

protected hookedModels: Set<string>

Defined in: packages/core/src/services/binary.service.ts:1579

Identifiers of the models whose deletion is already followed, so a second init() does not cascade twice

logger​

protected logger: Logger

Defined in: packages/core/src/services/service.ts:192

Logger with class context

Inherited from​

Service.logger

metrics​

metrics: object

Defined in: packages/core/src/services/binary.service.ts:1376

Metrics

delete​

delete: Counter

download​

download: Counter

metadataUpdate​

metadataUpdate: Counter

upload​

upload: Counter

Overrides​

Service.metrics

name​

readonly name: string

Defined in: packages/core/src/services/iservice.ts:35

Name

Inherited from​

Service.name

parameters​

readonly parameters: T

Defined in: packages/core/src/services/iservice.ts:39

Parameters

Inherited from​

Service.parameters

pendingDeletes​

protected pendingDeletes: Map<string, { infos: object[]; model: string; uuid: string; }>

Defined in: packages/core/src/services/binary.service.ts:1570

Binaries of a deleted object, kept between the Delete (before) and Deleted (after) events of its repository

createConfiguration?​

static optional createConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:44

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.createConfiguration

filterConfiguration?​

static optional filterConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:49

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.filterConfiguration

Parameters​

static Parameters: typeof ServiceParameters = ServiceParameters

Defined in: packages/core/src/services/service.ts:175

Service parameters

Inherited from​

Service.Parameters

Methods​

__clean()​

abstract __clean(): Promise<void>

Defined in: packages/core/src/services/service.ts:539

Clean the service data, can only be used in test mode

Returns​

Promise<void>

Inherited from​

Service.__clean

_get()​

abstract _get(info): Promise<Readable>

Defined in: packages/core/src/services/binary.service.ts:1544

Parameters​

info​

BinaryMap

Returns​

Promise<Readable>

addListener()​

addListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:90

Add listener

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void | Promise<void>

the event listener

Returns​

this

this for chaining

See​

EventEmitter.addListener

Inherited from​

Service.addListener

addRoute()​

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/src/services/service.ts:400

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 = false

whether to override existing

Returns​

void

Inherited from​

Service.addRoute

authorizeClientEvent()​

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/src/services/service.ts:353

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​

Service.authorizeClientEvent

cascadeDelete()​

abstract cascadeDelete(info, uuid, attribute, model): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1871

Cascade the deletion of an object to one of its binaries: only the usage of (model, attribute, uuid) is removed, never the usage of another object sharing the deduplicated data

Parameters​

info​

BinaryMap

of the map

uuid​

string

of the object

attribute​

string

the binary attribute holding the map

model​

string

the model identifier of the object

Returns​

Promise<void>

checkMap()​

protected checkMap(object, property): void

Defined in: packages/core/src/services/binary.service.ts:1717

Check if a map is defined

Parameters​

object​

Model

the target object

property​

string

the property name

Returns​

void

completeUpload()​

completeUpload(object, property, hash): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1963

Attach a direct upload once the client declares it finished, after verifying the uploaded object

By default no pending upload is managed so throws 404

Parameters​

object​

CoreModelWithBinary

the model owning the binary

property​

string

the binary attribute

hash​

string

the hash announced in the challenge

Returns​

Promise<void>

computeParameters()​

computeParameters(): void

Defined in: packages/core/src/services/service.ts:214

Used to compute or derivate input parameter to attribute

Returns​

void

Deprecated​

Inherited from​

Service.computeParameters

delete()​

abstract delete(object, property, index?): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1493

Delete a binary

Parameters​

object​

Storable

The object uuid to get from the store

property​

string

The object property to add the file to

index?​

number

The index of the file to change in the property

Returns​

Promise<void>

Emits​

'binaryDelete'

deleteSuccess()​

deleteSuccess(object, property, index?): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1881

Delete success

Parameters​

object​

CoreModelWithBinary

the target object

property​

string

the property name

index?​

number

the index

Returns​

Promise<void>

the result

downloadTo()​

downloadTo(info, filename): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1518

Download a binary to a file

Parameters​

info​

BinaryMap

The reference stored in your target object

filename​

any

the filename

Returns​

Promise<void>

emit()​

emit<Key>(event, data): Promise<void>

Defined in: packages/core/src/services/service.ts:520

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

event​

Key

the event name

data​

E[Key]

the data to process

Returns​

Promise<void>

Inherited from​

Service.emit

get()​

get(info): Promise<Readable>

Defined in: packages/core/src/services/binary.service.ts:1502

Get a binary

Parameters​

info​

BinaryMap

The reference stored in your target object

Returns​

Promise<Readable>

the result

Emits​

'binaryGet'

getCapabilities()​

getCapabilities(): Record<string, any>

Defined in: packages/core/src/services/iservice.ts:89

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​

Service.getCapabilities

getClientEvents()​

getClientEvents(): string[]

Defined in: packages/core/src/services/service.ts:341

Return the events that an external system can subscribe to

Returns​

string[]

the list of results

Inherited from​

Service.getClientEvents

getFile()​

getFile(req): Promise<BinaryFile<{ }>>

Defined in: packages/core/src/services/binary.service.ts:1912

Get file either from multipart post or raw

Parameters​

req​

IOperationContext

the request

Returns​

Promise<BinaryFile<{ }>>

the result

getMaxListeners()​

getMaxListeners(): number

Defined in: packages/core/src/events/asynceventemitter.ts:97

Returns​

number

Inherited from​

Service.getMaxListeners

getMetric()​

getMetric<T>(type, configuration): T

Defined in: packages/core/src/services/service.ts:323

Add service name label

Type Parameters​

T​

T = Gauge<string> | Counter<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​

Service.getMetric

getName()​

getName(): string

Defined in: packages/core/src/services/service.ts:530

Get service name

Returns​

string

the result string

Inherited from​

Service.getName

getOpenApiReplacements()​

getOpenApiReplacements(): any

Defined in: packages/core/src/services/service.ts:429

Return variables for replacement in openapi

Returns​

any

the result

Inherited from​

Service.getOpenApiReplacements

getOperationId()​

getOperationId(id): string

Defined in: packages/core/src/services/service.ts:387

If undefined is returned it cancel the operation registration

Parameters​

id​

string

the identifier

Returns​

string

the result

Inherited from​

Service.getOperationId

getOperationName()​

protected getOperationName(): string

Defined in: packages/core/src/services/binary.service.ts:1936

Return the name of the service for OpenAPI

Returns​

string

the result string

getParameters()​

getParameters(): T

Defined in: packages/core/src/services/service.ts:222

Get the service parameters

Returns​

T

the result

Inherited from​

Service.getParameters

getRedirectUrlFromObject()​

getRedirectUrlFromObject(binaryMap, _context, _expires?): Promise<string>

Defined in: packages/core/src/services/binary.service.ts:1414

Get a UrlFromObject

Parameters​

binaryMap​

BinaryMap

the binary map definition

_context​

IOperationContext

the execution context

_expires?​

number = 30

the expiration time

Returns​

Promise<string>

the result

getRepository()​

protected getRepository(model): any

Defined in: packages/core/src/services/binary.service.ts:1638

Get the event emitting repository of a model

Parameters​

model​

any

the model class

Returns​

any

the repository

getService()​

getService<T>(name): ServicesMap[T]

Defined in: packages/core/src/services/service.ts:313

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​

Service.getService

getState()​

getState(): ServiceStates

Defined in: packages/core/src/services/service.ts:185

Get the current state

Returns​

ServiceStates

the result

Inherited from​

Service.getState

getStoredValue()​

protected getStoredValue(object, property): Promise<any>

Defined in: packages/core/src/services/binary.service.ts:1790

The attribute value as stored: the object is re-loaded from its repository so a link made by a concurrent request (another instance of the same object) is seen. Objects without a stored copy keep their own value.

Parameters​

object​

CoreModelWithBinary

the target object

property​

string

the property name

Returns​

Promise<any>

the attribute value

getUrl()​

getUrl(url, _methods): string

Defined in: packages/core/src/services/service.ts:364

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​

Service.getUrl

getUsageCount()​

abstract getUsageCount(hash): Promise<number>

Defined in: packages/core/src/services/binary.service.ts:1483

The store can retrieve how many time a binary has been used

Parameters​

hash​

string

Returns​

Promise<number>

handleBinary()​

handleBinary(modelName, attribute): -1 | 0 | 1 | 2

Defined in: packages/core/src/services/binary.service.ts:1428

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

hookDelete()​

protected hookDelete(model, attributes): void

Defined in: packages/core/src/services/binary.service.ts:1650

Cascade the deletion of a model to its binaries

Delete runs before the repository deletion: the object is loaded and its binaries are kept aside. Deleted only fires once the deletion succeeded, so a failed delete leaves the binaries untouched.

Parameters​

model​

any

the model class

attributes​

string[]

the candidate behavior attributes

Returns​

void

init()​

init(): Promise<BinaryService<T, E>>

Defined in: packages/core/src/services/binary.service.ts:1588

Listen to the deletion of every model owning a binary attribute that this service stores

Exactly one service owns an attribute: the one getBinaryStore resolves, so several binary services never cascade the same attribute twice.

Returns​

Promise<BinaryService<T, E>>

this

Overrides​

Service.init

initMetrics()​

initMetrics(): void

Defined in: packages/core/src/services/binary.service.ts:1386

Returns​

void

Overrides​

Service.initMetrics

initOperations()​

initOperations(): void

Defined in: packages/core/src/services/service.ts:459

Init the operations from

Returns​

void

Operation​

decorators on this service

Inherited from​

Service.initOperations

isCollection()​

protected isCollection(object, property): boolean

Defined in: packages/core/src/services/binary.service.ts:1736

Whether the binary attribute is a collection (BinariesImpl or a subclass) rather than a single Binary

Models are hydrated by the compiled __hydrateBehaviors (store deserialization, load, patch), which always instantiates the behavior class, even for an unset attribute: instanceof BinariesImpl therefore covers subclasses. The relation id comparison is the fallback for objects that were never hydrated.

Parameters​

object​

CoreModelWithBinary

the target object

property​

string

the property name

Returns​

boolean

true if the attribute holds several binaries

isLinked()​

protected isLinked(object, property, hash, value?): boolean

Defined in: packages/core/src/services/binary.service.ts:1771

Whether the hash is already linked to the object attribute (a collection item or the single binary)

Parameters​

object​

CoreModelWithBinary

the target object

property​

string

the property name

hash​

string

the binary hash

value?​

any = ...

the attribute value to check, default to the object's

Returns​

boolean

true if linked

listeners()​

listeners(eventName): Function[]

Defined in: packages/core/src/events/asynceventemitter.ts:195

Get all listeners for an event

Parameters​

eventName​

keyof E

the event name

Returns​

Function[]

the list of results

Inherited from​

Service.listeners

loadCapabilities()​

protected loadCapabilities(): void

Defined in: packages/core/src/services/service.ts:283

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​

Service.loadCapabilities

log()​

log(level, ...args): void

Defined in: packages/core/src/services/service.ts:561

Log operation

Parameters​

level​

WorkerLogLevel

to log

args​

...any[]

additional arguments

Returns​

void

Inherited from​

Service.log

newModel()​

newModel(obj): BinaryMap

Defined in: packages/core/src/services/binary.service.ts:1551

Based on the raw Map init a BinaryMap

Parameters​

obj​

any

the target object

Returns​

BinaryMap

the result map

Implementation of​

MappingService.newModel

off()​

off<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:152

Perform off

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.off

Inherited from​

Service.off

on()​

on<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:128

Perform on

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.on

once()​

once<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:116

Perform once

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.once

operationSchemaName()​

protected operationSchemaName(method, side): string

Defined in: packages/core/src/services/service.ts:441

Schema of an operation side: <service name>.<method>.<side> when the application knows it, else the one the build writes, <class>.<method>.<side>, for the class or its nearest ancestor that has it (a service configured under another name than its class)

Parameters​

method​

string

the method name

side​

"input" | "output"

input or output

Returns​

string

the schema name

Inherited from​

Service.operationSchemaName

ownsAttribute()​

protected ownsAttribute(model, attribute): boolean

Defined in: packages/core/src/services/binary.service.ts:1620

Whether this service is the one storing the binaries of a model attribute

Parameters​

model​

any

the model class

attribute​

string

the attribute name

Returns​

boolean

true if owned

putRedirectUrl()​

putRedirectUrl(...args): Promise<{ headers?: {[key: string]: string; }; method?: string; url: string; }>

Defined in: packages/core/src/services/binary.service.ts:1972

By default no challenge is managed so throws 404

Parameters​

args​

...any

additional arguments

Returns​

Promise<{ headers?: {[key: string]: string; }; method?: string; url: string; }>

removeAllListeners()​

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/src/events/asynceventemitter.ts:162

Remove all listeners

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName?​

Key

the event name

Returns​

this

this for chaining

See​

EventEmitter.removeAllListeners

Inherited from​

Service.removeAllListeners

removeListener()​

removeListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:140

Remove listener

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.removeListener

Inherited from​

Service.removeListener

resolve()​

resolve(): this

Defined in: packages/core/src/services/service.ts:249

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​

Service.resolve

setMaxListeners()​

setMaxListeners(n): this

Defined in: packages/core/src/events/asynceventemitter.ts:104

Parameters​

n​

number

Returns​

this

Inherited from​

Service.setMaxListeners

stop()​

stop(): Promise<void>

Defined in: packages/core/src/services/service.ts:230

Shutdown the current service if action need to be taken

Returns​

Promise<void>

Inherited from​

Service.stop

store()​

abstract store(object, property, file, metadata?): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1478

When you store a binary to be able to retrieve it you need to store the information into another object

If you have a User object define like this : User = {'name': 'Remi', 'uuid': 'Loopingz'} You will call the store(userStore, 'Loopingz', 'images', filedata, {'type':'profile'}) After a successful call the object will look like

User = {
 'name': 'Remi',
 'uuid': 'Loopingz',
 'images': [
   {'type':'profile','hash':'a12545...','size':1245,'mime':'application/octet'}
  ]
}

Parameters​

object​

Storable

The object uuid to get from the store

property​

string

The object property to add the file to

file​

BinaryFile

The file by itself

metadata?​

any

to add to the binary object

Returns​

Promise<void>

Emits​

'binaryCreate'

toJSON()​

toJSON(): string

Defined in: packages/core/src/services/service.ts:499

Prevent service to be serialized

Returns​

string

the result

Inherited from​

Service.toJSON

toString()​

toString(): string

Defined in: packages/core/src/services/service.ts:238

Return service representation

Returns​

string

the result

Inherited from​

Service.toString

uploadSuccess()​

uploadSuccess(object, property, fileInfo): Promise<void>

Defined in: packages/core/src/services/binary.service.ts:1811

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>

verifiedHashes()​

protected verifiedHashes(file): Promise<{ challenge: string; hash: string; }>

Defined in: packages/core/src/services/binary.service.ts:1753

Hashes of a file to store, computed from its bytes: a hash or challenge set on the file is never trusted

A preset hash that differs from the content is rejected; the file then carries the computed values

Parameters​

file​

BinaryFile

the file to store

Returns​

Promise<{ challenge: string; hash: string; }>

the computed hash and challenge

verifyMapAndStore()​

protected verifyMapAndStore(ctx): IStore

Defined in: packages/core/src/services/binary.service.ts:1945

Based on the request parameter verify it match a known mapping

Parameters​

ctx​

IOperationContext

the operation context

Returns​

IStore

the result

streamToBuffer()​

static streamToBuffer(stream): Promise<Buffer<ArrayBufferLike>>

Defined in: packages/core/src/services/binary.service.ts:1561

Read a stream to a buffer

Parameters​

stream​

Readable

the stream

Returns​

Promise<Buffer<ArrayBufferLike>>

the result