@webda/core 1.2.1 → 1.6.0-beta.0

package/lib/services/binary.d.ts

@@ -1,11 +1,20 @@
+/// <reference types="node" />
+import { Readable } from "stream";
+import { WebdaError } from "..";
 import { CoreModel } from "../models/coremodel";
-import { Store } from "../stores/store";
+import { MappingService, Store } from "../stores/store";
 import { Context } from "../utils/context";
 import { Service, ServiceParameters } from "./service";
+/**
+ * Represent basic EventBinary
+ */
 export interface EventBinary {
     object: BinaryMap;
     service: Binary;
 }
+/**
+ * Emitted when someone download a binary
+ */
 export interface EventBinaryGet extends EventBinary {
 }
 export interface EventBinaryUploadSuccess extends EventBinary {
@@ -15,8 +24,52 @@ export interface EventBinaryDelete extends EventBinary {
 }
 export interface EventBinaryCreate extends EventBinaryUploadSuccess {
 }
-export interface EventBinaryUpdate extends EventBinaryUploadSuccess {
-    old: BinaryMap;
+/**
+ * Emitted if binary does not exist
+ */
+export declare class BinaryNotFoundError extends WebdaError {
+    constructor(hash: string, storeName: string);
+}
+/**
+ * Represent a file to store
+ */
+export interface BinaryFile {
+    /**
+     * Path on the hard drive
+     */
+    path?: string;
+    /**
+     * Content
+     */
+    buffer?: Buffer;
+    /**
+     * Current name
+     */
+    name?: string;
+    /**
+     * Original name
+     */
+    originalname?: string;
+    /**
+     * Size of the binary
+     */
+    size?: number;
+    /**
+     * Mimetype of the binary
+     */
+    mimetype?: string;
+    /**
+     * Will be computed by the service
+     *
+     * hash of the content prefixed by 'WEBDA'
+     */
+    challenge?: string;
+    /**
+     * Will be computed by the service
+     *
+     * hash of the content
+     */
+    hash?: string;
 }
 /**
  * This is a map used to retrieve binary
@@ -24,26 +77,44 @@ export interface EventBinaryUpdate extends EventBinaryUploadSuccess {
  * @class BinaryMap
  */
 export declare class BinaryMap {
+    /**
+     * Current context
+     */
     __ctx: Context;
+    /**
+     * Link to the binary store
+     */
     __store: Binary;
     /**
      * Hash of the binary
      */
     hash: string;
+    /**
+     * Size of the file
+     */
+    size: number;
+    /**
+     * Mimetype
+     */
+    mime: string;
     constructor(service: any, obj: any);
     /**
-     * Get the CoreModel
+     * Prevent all the attributes starting with '__' to be serialized
+     * @returns
+     */
+    toJSON(): {};
+    /**
+     * Get the binary data
      *
      * @returns
      */
-    get(): Promise<ReadableStream<any>>;
+    get(): Promise<Readable>;
     /**
      * Download the binary to a path
      *
      * Shortcut to call {@link Binary.downloadTo} with current object
      *
      * @param filename
-     * @returns
      */
     downloadTo(filename: string): Promise<void>;
     /**
@@ -55,6 +126,9 @@ export declare class BinaryMap {
 export declare class BinaryParameters extends ServiceParameters {
     /**
      * Define the map to Object collection
+     *
+     * key is a Store name
+     * the string[] represent all valids attributes to store files in
      */
     map: {
         [key: string]: string[];
@@ -89,8 +163,16 @@ export declare class BinaryParameters extends ServiceParameters {
 }
 /**
  * This is an abstract service to represent a storage of files
- * The binary allow you to expose this service as HTTP ( therefore is an executor )
- * It needs an object to attach the binary too
+ * 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.
  *
@@ -102,12 +184,8 @@ export declare class BinaryParameters extends ServiceParameters {
  * @abstract
  * @class Binary
  */
-declare abstract class Binary<T extends BinaryParameters = BinaryParameters> extends Service<T> {
+declare abstract class Binary<T extends BinaryParameters = BinaryParameters> extends Service<T> implements MappingService<BinaryMap> {
     _lowercaseMaps: any;
-    /**
-     * @inheritdoc
-     */
-    loadParameters(params: any): ServiceParameters;
     /**
      * When you store a binary to be able to retrieve it you need to store the information into another object
      *
@@ -125,68 +203,88 @@ declare abstract class Binary<T extends BinaryParameters = BinaryParameters> ext
      * ```
      *
      *
-     * @param {Store} targetStore The store that handles the object to attach binary to
      * @param {CoreModel} object The object uuid to get from the store
      * @param {String} property The object property to add the file to
      * @param {Object} file The file by itself
      * @param {Object} metadatas to add to the binary object
      * @emits 'binaryCreate'
      */
-    abstract store(targetStore: Store<CoreModel>, object: CoreModel, property: string, file: any, metadatas: any, index?: number): Promise<any>;
+    abstract store(object: CoreModel, property: string, file: BinaryFile, metadatas?: {
+        [key: string]: any;
+    }): Promise<void>;
     /**
      * The store can retrieve how many time a binary has been used
      */
     abstract getUsageCount(hash: any): Promise<number>;
     /**
-     * Update a binary
-     *
+     * Delete a binary
      *
-     * @param {Store} targetStore The store that handles the object to attach binary to
-     * @param {String} object The object uuid to get from the store
-     * @param {String} property The object property to add the file to
-     * @param {Number} index The index of the file to change in the property
-     * @param {Object} file The file by itself
-     * @param {Object} metadatas to add to the binary object
-     * @emits 'binaryUpdate'
-     */
-    abstract update(targetStore: any, object: any, property: any, index: any, file: any, metadatas: any): Promise<CoreModel>;
-    /**
-     * Update a binary
-     *
-     *
-     * @param {Store} targetStore The store that handles the object to attach binary to
      * @param {CoreModel} object The object uuid to get from the store
      * @param {String} property The object property to add the file to
      * @param {Number} index The index of the file to change in the property
      * @emits 'binaryDelete'
      */
-    abstract delete(targetStore: Store<CoreModel>, object: CoreModel, property: string, index: number): Promise<CoreModel>;
+    abstract delete(object: CoreModel, property: string, index: number): Promise<void>;
     /**
      * Get a binary
      *
      * @param {Object} info The reference stored in your target object
      * @emits 'binaryGet'
      */
-    get(info: BinaryMap): Promise<ReadableStream<any>>;
+    get(info: BinaryMap): Promise<Readable>;
     /**
      * Download a binary to a file
      *
      * @param {Object} info The reference stored in your target object
      * @param {String} filepath to save the binary to
      */
-    downloadTo(info: any, filename: any): Promise<void>;
-    /** @ignore */
-    init(): Promise<void>;
-    _getUrl(info: any, ctx: Context): void;
-    _get(info: any): ReadableStream;
+    downloadTo(info: BinaryMap, filename: any): Promise<void>;
+    /**
+     * @override
+     */
+    resolve(): void;
+    abstract _get(info: BinaryMap): Promise<Readable>;
+    /**
+     * Init the declared maps, adding reverse maps
+     *
+     * @param map
+     */
     initMap(map: any): void;
+    /**
+     * Based on the raw Map init a BinaryMap
+     * @param obj
+     * @returns
+     */
     initModel(obj: any): BinaryMap;
-    _getHashes(buffer: any): any;
-    _prepareInput(file: any): void;
-    _checkMap(name: any, property: any): void;
-    _validChallenge(challenge: any): boolean;
-    challenge(hash: any, challenge: any): boolean;
-    updateSuccess(targetStore: Store, object: CoreModel, property: string, index: number, file: any, metadatas: any): Promise<any>;
+    /**
+     * Create hashes
+     * @param buffer
+     * @returns
+     */
+    _getHashes(buffer: Buffer): {
+        hash: string;
+        challenge: string;
+    };
+    /**
+     * Read a stream to a buffer
+     *
+     * @param stream
+     * @returns
+     */
+    static streamToBuffer(stream: Readable): Promise<Buffer>;
+    /**
+     * Update the BinaryFile
+     * @param file
+     */
+    _prepareInput(file: BinaryFile): void;
+    /**
+     * Check if a map is defined
+     *
+     * @param name
+     * @param property
+     */
+    _checkMap(name: string, property: string): void;
+    uploadSuccess(object: CoreModel, property: string, file: any, metadatas?: any): Promise<void>;
     /**
      * Cascade delete the object
      *
@@ -202,20 +300,49 @@ declare abstract class Binary<T extends BinaryParameters = BinaryParameters> ext
      * @param index
      * @returns
      */
-    deleteSuccess(targetStore: Store, object: CoreModel, property: string, index: number): Promise<any>;
-    _getFile(req: any): any;
+    deleteSuccess(object: CoreModel, property: string, index: number): Promise<void>;
+    /**
+     * Get file either from multipart post or raw
+     * @param req
+     * @returns
+     */
+    _getFile(req: Context): any;
     /**
      * Init the Binary system routes
      */
     initRoutes(): void;
+    /**
+     * Return the name of the service for OpenAPI
+     * @returns
+     */
+    protected getOperationName(): string;
     /**
      * This is used to allow subclasses to add more route
      */
     _initRoutes(): boolean;
-    httpPost(ctx: Context): Promise<void>;
+    /**
+     * Based on the request parameter verify it match a known mapping
+     * @param ctx
+     * @returns
+     */
     _verifyMapAndStore(ctx: Context): Store<CoreModel>;
-    putRedirectUrl(ctx: Context): Promise<string>;
+    /**
+     * By default no challenge is managed so throws 404
+     *
+     * @param ctx
+     */
+    putRedirectUrl(ctx: Context): Promise<{
+        url: string;
+        method?: string;
+    }>;
+    /**
+     * Mechanism to add a data based on challenge
+     */
     httpChallenge(ctx: Context): Promise<void>;
+    /**
+     * Manage the different routes
+     * @param ctx
+     */
     httpRoute(ctx: Context): Promise<void>;
 }
 export { Binary };