Class FileUrlTrait

File URL Trait provides downloadUrl and uploadUrl query fields and global setFileUploaded mutation triggered by S3 file upload Lambda.

Usage:

traits:
  - type: file_url

Mermaid

Media file upload

%%{init:{"theme":"dark"}}%% sequenceDiagram actor User participant Kosmos participant S3 participant S3 Lambda Trigger User->>Kosmos: GraphQL mutation creating file entity activate Kosmos Kosmos->>User: Response with file UUID and signed S3 upload URL deactivate Kosmos User->>S3: File upload S3->>User: OK S3->>S3 Lambda Trigger: Trigger upload event S3 Lambda Trigger->>Kosmos: GraphQL mutation confirming file was uploaded activate Kosmos Kosmos->>S3 Lambda Trigger: OK deactivate Kosmos

%%{init:{"theme":"default"}}%% sequenceDiagram actor User participant Kosmos participant S3 participant S3 Lambda Trigger User->>Kosmos: GraphQL mutation creating file entity activate Kosmos Kosmos->>User: Response with file UUID and signed S3 upload URL deactivate Kosmos User->>S3: File upload S3->>User: OK S3->>S3 Lambda Trigger: Trigger upload event S3 Lambda Trigger->>Kosmos: GraphQL mutation confirming file was uploaded activate Kosmos Kosmos->>S3 Lambda Trigger: OK deactivate Kosmos

sequenceDiagram
    actor User
    participant Kosmos
    participant S3
    participant S3 Lambda Trigger
    User->>Kosmos: GraphQL mutation creating file entity
    activate Kosmos
    Kosmos->>User: Response with file UUID and signed S3 upload URL
    deactivate Kosmos
    User->>S3: File upload
    S3->>User: OK
    S3->>S3 Lambda Trigger: Trigger upload event
    S3 Lambda Trigger->>Kosmos: GraphQL mutation confirming file was uploaded
    activate Kosmos
    Kosmos->>S3 Lambda Trigger: OK
    deactivate Kosmos

Mermaid

Retrieving file entity before file was uploaded

%%{init:{"theme":"dark"}}%% sequenceDiagram actor User participant Kosmos participant S3 User->>Kosmos: GraphQL query retrieving file entity activate Kosmos Kosmos->>User: Response with empty file download URL deactivate Kosmos

%%{init:{"theme":"default"}}%% sequenceDiagram actor User participant Kosmos participant S3 User->>Kosmos: GraphQL query retrieving file entity activate Kosmos Kosmos->>User: Response with empty file download URL deactivate Kosmos

sequenceDiagram
    actor User
    participant Kosmos
    participant S3
    User->>Kosmos: GraphQL query retrieving file entity
    activate Kosmos
    Kosmos->>User: Response with empty file download URL
    deactivate Kosmos

Mermaid

Retrieving file entity after file was uploaded

sequenceDiagram
    actor User
    participant Kosmos
    participant S3
    User->>Kosmos: GraphQL query retrieving file entity
    activate Kosmos
    Kosmos->>User: Response with signed file download URL
    deactivate Kosmos
    User->>S3: GET file by signed URL
    S3->>User: File object

Hierarchy

Trait<FileUrlTraitConfig>
- FileUrlTrait

Constructors

constructor

new FileUrlTrait(runtimeConfig: RuntimeConfig, graphqlSchemaManager: GraphQLSchemaManager, dataSourceWrapper: DataSourceWrapper, accessControl: AccessControl, cacheService: CacheService): FileUrlTrait
Parameters
- runtimeConfig: RuntimeConfig
- graphqlSchemaManager: GraphQLSchemaManager
- dataSourceWrapper: DataSourceWrapper
- accessControl: AccessControl
- cacheService: CacheService
Returns FileUrlTrait
Overrides Trait.constructor
- Defined in src/traits/FileUrlTrait.ts:117

Properties

`Private` `Readonly` _cacheEnabled

_cacheEnabled: boolean

`Protected` `Optional` _config

_config?: FileUrlTraitConfig

Trait instance configuration.

`Protected` _global

_global: boolean = false

Whether this is a global (not bound to any specific schema item) trait instance.

`Protected` `Optional` _type

_type?: "file_url"

Trait type.

`Protected` `Readonly` accessControl

accessControl: AccessControl

`Protected` `Readonly` cacheService

cacheService: CacheService

`Protected` `Readonly` dataSourceWrapper

dataSourceWrapper: DataSourceWrapper

`Protected` `Readonly` graphqlSchemaManager

graphqlSchemaManager: GraphQLSchemaManager

`Protected` `Readonly` runtimeConfig

runtimeConfig: RuntimeConfig

`Static` s3Client

s3Client: S3

Methods

_deleteFileFromS3

_deleteFileFromS3(s3FileKey: string): Promise<void>
Deletes a file from S3.
Parameters
- s3FileKey: string
  
  The S3 object key of the file to be deleted.
Returns Promise<void>
- Defined in src/traits/FileUrlTrait.ts:386

`Private` _fileUploaded

_fileUploaded(datasourceWrapper: DataSourceWrapper, traitData: TraitDataObject<{
id: string;
}, Record<string, any>, Promise<any>>): Promise<boolean>
Checks if given media file was uploaded to S3.
Parameters
- datasourceWrapper: DataSourceWrapper
- traitData: TraitDataObject<{
  id: string;
  }, Record<string, any>, Promise<any>>
Returns Promise<boolean>
- Defined in src/traits/FileUrlTrait.ts:481

`Private` _generateS3Key

_generateS3Key(item: FileKosmosItem): string
Generate S3 object key for a file.
Parameters
- item: FileKosmosItem
Returns string
- Defined in src/traits/FileUrlTrait.ts:474

`Private` _getContextStorage

_getContextStorage(traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>): FileUrlTraitStorage
Helper method which initializes/returns RepositoryTrait storage object.
Parameters
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
Returns FileUrlTraitStorage
- Defined in src/traits/FileUrlTrait.ts:536

_s3Client

_s3Client(): S3
S3 client singleton.

Returns S3
- Defined in src/traits/FileUrlTrait.ts:443

`Private` _s3FileExists

_s3FileExists(s3FileKey: string): Promise<boolean>
Checks if given file exists at S3.
Parameters
- s3FileKey: string
Returns Promise<boolean>
- Defined in src/traits/FileUrlTrait.ts:522

`Private` _sanitizeFilename

_sanitizeFilename(item: FileKosmosItem): string
Returns sanitized file URL.
Parameters
- item: FileKosmosItem
Returns string
- Defined in src/traits/FileUrlTrait.ts:461

downloadUrlHandler

downloadUrlHandler(datasourceWrapper: DataSourceWrapper, traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>): Promise<null | string>
Download URL field resolver.
Parameters
- datasourceWrapper: DataSourceWrapper
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
Returns Promise<null | string>
- Defined in src/traits/FileUrlTrait.ts:237

hookIntoSchema

hookIntoSchema(schemaItem: SchemaItem<SchemaItemType>): void
Parameters
- schemaItem: SchemaItem<SchemaItemType>
Returns void
Overrides Trait.hookIntoSchema
- Defined in src/traits/FileUrlTrait.ts:187

hookIntoSchemaManager

hookIntoSchemaManager(): void
Attaches Trait callbacks to schema manager hooks.

Returns void
Inherited from Trait.hookIntoSchemaManager
- Defined in src/traits/Trait.ts:225

makeGlobal

makeGlobal(): FileUrlTrait
Makes this Trait instance global.

Returns FileUrlTrait
Inherited from Trait.makeGlobal
- Defined in src/traits/Trait.ts:237

mutationSchema

mutationSchema(schemaString: string): string
Defines mutation schema for updating file upload status.
Parameters
- schemaString: string
Returns string
- Defined in src/traits/FileUrlTrait.ts:177

name

name(): string
Used to return the name.

Returns string
Inherited from Trait.name
- Defined in src/traits/Trait.ts:198

postCreate

postCreate(traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>, item: StoredKosmosItem, datasourceWrapper: DataSourceWrapper, context: KosmosUserContext<object>): Promise<void>
Post-create hook implementation.

Sets file S3 path. This is done on postCreate() since the entity ID is used in URL key.
Parameters
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
- item: StoredKosmosItem
- datasourceWrapper: DataSourceWrapper
- context: KosmosUserContext<object>
Returns Promise<void>
- Defined in src/traits/FileUrlTrait.ts:338

postDelete

postDelete(traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>, item: StoredKosmosItem): Promise<void>
Post-delete hook implementation.

Deletes the associated file from S3 when a vertex is deleted.
Parameters
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
- item: StoredKosmosItem
Returns Promise<void>
- Defined in src/traits/FileUrlTrait.ts:371

preCreate

preCreate(traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>): Promise<void>
Pre-create hook implementation.

Verifies filename.
Parameters
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
Returns Promise<void>
- Defined in src/traits/FileUrlTrait.ts:314

process

process<RT, Payload>(callbackName: string, datasourceWrapper: DataSourceWrapper, data: TraitDataObject<RT, Payload, Promise<any>>): Promise<RT>
This method is triggered when a trait callback has been activated
Type Parameters
- RT = any
- Payload = any
Parameters
- callbackName: string
  
  This is the name of the callback function to call.
- datasourceWrapper: DataSourceWrapper
  
  References to the Graph Hanlder
- data: TraitDataObject<RT, Payload, Promise<any>>
  
  Request data passed along as part of the request.
Returns Promise<RT>
Inherited from Trait.process
- Defined in src/traits/Trait.ts:147

querySchema

querySchema(schemaString: string): string
Adds downloadUrl and uploadUrl fields definitions.

TODO: Remove resolvers assignment; this hook should only return a schema string. Resolvers (or 'handlers' should be defined and retrieved via separate hook).

Updated GraphQL query schema string.
Parameters
- schemaString: string
Returns string
- Defined in src/traits/FileUrlTrait.ts:157

setConfig

setConfig(config: FileUrlTraitConfig): void
Configuration setter.
Parameters
- config: FileUrlTraitConfig
  
  The new configuration.
Returns void
Overrides Trait.setConfig
- Defined in src/traits/FileUrlTrait.ts:134

setFileUploaded

setFileUploaded(datasourceWrapper: DataSourceWrapper, traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>): Promise<boolean>
Updates file upload status.
Parameters
- datasourceWrapper: DataSourceWrapper
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
Returns Promise<boolean>
- Defined in src/traits/FileUrlTrait.ts:400

traitConfig

traitConfig(): FileUrlTraitConfig
Returns FileUrlTraitConfig
Inherited from Trait.traitConfig
- Defined in src/traits/Trait.ts:205

uploadUrlHandler

uploadUrlHandler(datasourceWrapper: DataSourceWrapper, traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>): Promise<null | string>
Upload URL field resolver.
Parameters
- datasourceWrapper: DataSourceWrapper
- traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>
Returns Promise<null | string>
- Defined in src/traits/FileUrlTrait.ts:270

wrapLegacyResolver

wrapLegacyResolver<RT, Payload>(resolver: LegacyKosmosTraitResolverCallback<RT, any>, datasourceWrapper: DataSourceWrapper, callbackName?: string): KosmosGraphQLResolver<RT, Payload, Promise<RT>>
Helper method for wrapping legacy Kosmos traits callbacks.

TODO: Remove this method once all Traits are converted.
Type Parameters
- RT = any
- Payload = any
Parameters
- resolver: LegacyKosmosTraitResolverCallback<RT, any>
- datasourceWrapper: DataSourceWrapper
- Optional callbackName: string
  
  Optional callback name; passing this parameter will additionally wrap the callback into legacy process().
Returns KosmosGraphQLResolver<RT, Payload, Promise<RT>>
Inherited from Trait.wrapLegacyResolver
- Defined in src/traits/Trait.ts:168

`Static` traitTypeName

traitTypeName(): string
This method should return the trait machine name(s).

Returns

Returns string
Overrides Trait.traitTypeName
- Defined in src/traits/FileUrlTrait.ts:143

Class FileUrlTrait

Mermaid

Media file upload

Mermaid

Retrieving file entity before file was uploaded

Mermaid

Retrieving file entity after file was uploaded

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

runtimeConfig: RuntimeConfig

graphqlSchemaManager: GraphQLSchemaManager

dataSourceWrapper: DataSourceWrapper

accessControl: AccessControl

cacheService: CacheService

Returns FileUrlTrait

Properties

Private Readonly _cacheEnabled

Protected Optional _config

Protected _global

Protected Optional _type

Protected Readonly accessControl

Protected Readonly cacheService

Protected Readonly dataSourceWrapper

Protected Readonly graphqlSchemaManager

Protected Readonly runtimeConfig

Static s3Client

Methods

_deleteFileFromS3

Parameters

s3FileKey: string

Returns Promise<void>

Private _fileUploaded

Parameters

datasourceWrapper: DataSourceWrapper

traitData: TraitDataObject<{ id: string; }, Record<string, any>, Promise<any>>

Returns Promise<boolean>

Private _generateS3Key

Parameters

item: FileKosmosItem

Returns string

Private _getContextStorage

Parameters

traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>

Returns FileUrlTraitStorage

_s3Client

Returns S3

Private _s3FileExists

Parameters

s3FileKey: string

Returns Promise<boolean>

Private _sanitizeFilename

Parameters

item: FileKosmosItem

Returns string

downloadUrlHandler

Parameters

datasourceWrapper: DataSourceWrapper

traitData: TraitDataObject<unknown, Record<string, any>, Promise<any>>

Returns Promise<null | string>

hookIntoSchema

Parameters

schemaItem: SchemaItem<SchemaItemType>

Returns void

hookIntoSchemaManager

Returns void

makeGlobal

Returns FileUrlTrait

mutationSchema

Parameters

schemaString: string

Returns string

name

Returns string

postCreate

`Private` `Readonly` _cacheEnabled

`Protected` `Optional` _config

`Protected` _global

`Protected` `Optional` _type

`Protected` `Readonly` accessControl

`Protected` `Readonly` cacheService

`Protected` `Readonly` dataSourceWrapper

`Protected` `Readonly` graphqlSchemaManager

`Protected` `Readonly` runtimeConfig

`Static` s3Client

`Private` _fileUploaded

traitData: TraitDataObject<{
id: string;
}, Record<string, any>, Promise<any>>

`Private` _generateS3Key

`Private` _getContextStorage

`Private` _s3FileExists

`Private` _sanitizeFilename

`Optional` callbackName: string

`Static` traitTypeName