The mito-attachment Reference Manual

Table of Contents

The mito-attachment Reference Manual

This is the mito-attachment Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:17:24 2018 GMT+0.

1 Introduction

mito-attachment

The place to store files would be a problem when you intend to write a web application which allows file-uploading. These days, AWS S3 is a common place to store/serve files, however, it's not easy to manage like RDBMS.

Mito-attachment provides a Mito mixin class for managing files outside of RDBMS. It stores files before mito:save-dao and deletes them before mito:delete-dao.

Besides, the backend storage can be replaced easily. This makes it easy that using cloud storage services for production environment and using local filesystem for development environment.

Usage

Setting up the storage

(defvar *appenv* (uiop:getenv "APP_ENV"))

;; Setup storage class
(setf *storage*
      (if (string= *appenv* "production")
          ;; Store files in AWS S3 for production environment
          (make-instance 's3-storage
                         :bucket "mito-attachment-example"
                         :endpoint "s3-ap-northeast-1.amazonaws.com"
                         :access-key (uiop:getenv "AWS_ACCESS_KEY")
                         :secret-key (uiop:getenv "AWS_SECRET_KEY"))
          ;; Store files in local filesystem for development environment
          (make-instance 'disk-storage
                         :bucket "mito-attachment-example"
                         :directory #P"/tmp/attachment/")))

Defining an attachment Mito class

;; Attachment class for saving metadata into RDBMS
(defclass image (attachment) ()
  (:metaclass mito:dao-table-class))

Saving

;; :content can be specified as a pathname or a stream.
(mito:create-dao 'image :content #P"uploaded-file.png")

;; Override the file content-type
(mito:create-dao 'image :content #P"uploaded-file.png" :content-type "image/png")

;; Use an original file-key
(mito:create-dao 'image :content #P"uploaded-file.png" :file-key "image.png")

Getting the URL

(let ((file (mito:find-dao 'image :id 1)))
  (file-url file))
;-> ;; SELECT * FROM "image" WHERE ("id" = ?) LIMIT 1 (1) [1 row] | MITO.DB:RETRIEVE-BY-SQL
;=> "/mito-attachment-example/3616D80112884799B272DC962F4BBF97.jpg"

See example.lisp for getting the full example. It's a Lack web application which allows users to upload image files.

Installation

(ql:quickload :mito-attachment)

See Also

• Mito
• Clipper for Integral

Author

• Eitaro Fukamachi (e.arrows@gmail.com)

Copyright

Copyright (c) 2016 Eitaro Fukamachi (e.arrows@gmail.com)

License

Licensed under the LLGPL License.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 mito-attachment

Author

Eitaro Fukamachi

License

LLGPL

Description

Mito mixin class for file management

Long Description

# mito-attachment

The place to store files would be a problem when you intend to write a web application which allows file-uploading. These days, AWS S3 is a common place to store/serve files, however, it’s not easy to manage like RDBMS.

Mito-attachment provides a Mito mixin class for managing files outside of RDBMS. It stores files before ‘mito:save-dao‘ and deletes them before ‘mito:delete-dao‘.

Besides, the backend storage can be replaced easily. This makes it easy that using cloud storage services for production environment and using local filesystem for development environment.

## Usage

### Setting up the storage

“‘common-lisp
(defvar *appenv* (uiop:getenv "APP_ENV"))

;; Setup storage class
(setf *storage*
(if (string= *appenv* "production")
;; Store files in AWS S3 for production environment
(make-instance ’s3-storage
:bucket "mito-attachment-example"
:endpoint "s3-ap-northeast-1.amazonaws.com"
:access-key (uiop:getenv "AWS_ACCESS_KEY")
:secret-key (uiop:getenv "AWS_SECRET_KEY"))
;; Store files in local filesystem for development environment
(make-instance ’disk-storage
:bucket "mito-attachment-example"
:directory #P"/tmp/attachment/")))

“‘

### Defining an attachment Mito class

“‘common-lisp
;; Attachment class for saving metadata into RDBMS
(defclass image (attachment) ()
(:metaclass mito:dao-table-class))
“‘

### Saving

“‘common-lisp
;; :content can be specified as a pathname or a stream.
(mito:create-dao ’image :content #P"uploaded-file.png")

;; Override the file content-type
(mito:create-dao ’image :content #P"uploaded-file.png" :content-type "image/png")

;; Use an original file-key
(mito:create-dao ’image :content #P"uploaded-file.png" :file-key "image.png")
“‘

### Getting the URL

“‘common-lisp
(let ((file (mito:find-dao ’image :id 1)))
(file-url file))
;-> ;; SELECT * FROM "image" WHERE ("id" = ?) LIMIT 1 (1) [1 row] | MITO.DB:RETRIEVE-BY-SQL
;=> "/mito-attachment-example/3616D80112884799B272DC962F4BBF97.jpg"
“‘

See [example.lisp](example.lisp) for getting the full example. It’s a Lack web application which allows users to upload image files.

## Installation

“‘common-lisp
(ql:quickload :mito-attachment)
“‘

## See Also

* [Mito](https://github.com/fukamachi/mito)
* [Clipper](https://github.com/Rudolph-Miller/clipper) for Integral

## Author

* Eitaro Fukamachi (e.arrows@gmail.com)

## Copyright

Copyright (c) 2016 Eitaro Fukamachi (e.arrows@gmail.com)

## License

Licensed under the LLGPL License.

Version

0.1

Dependencies

• mito
• zs3
• lack-component
• trivial-mimes
• uuid
• cl-reexport
• uiop
• alexandria

Source

mito-attachment.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 mito-attachment/src

Parent

mito-attachment (system)

Location

src/

Components

• mito-attachment.lisp (file)
• mixin.lisp (file)
• storage.lisp (file)
• storage-components (module)

3.2 mito-attachment/src/storage-components

Dependency

storage.lisp (file)

Parent

src (module)

Location

src/storage/

Components

• disk.lisp (file)
• s3.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 mito-attachment.asd

Location

mito-attachment.asd

Systems

mito-attachment (system)

Packages

mito-attachment-asd

4.1.2 mito-attachment/src/mito-attachment.lisp

Dependencies

• mixin.lisp (file)
• storage.lisp (file)
• storage-components (module)

Parent

src (module)

Location

src/mito-attachment.lisp

Packages

mito-attachment

4.1.3 mito-attachment/src/mixin.lisp

Dependency

storage.lisp (file)

Parent

src (module)

Location

src/mixin.lisp

Packages

mito.attachment.mixin

Exported Definitions

• attachment (class)
• content (method)
• (setf content) (method)
• (setf content) (method)
• content-type (method)
• (setf content-type) (method)
• file-key (method)
• (setf file-key) (method)
• file-size (method)
• (setf file-size) (method)
• file-url (generic function)
• file-url (method)

Internal Definitions

• initialize-with-content (function)
• slurp-stream (function)

4.1.4 mito-attachment/src/storage.lisp

Parent

src (module)

Location

src/storage.lisp

Packages

mito.attachment.storage

Exported Definitions

• *storage* (special variable)
• delete-object-from-storage (generic function)
• storage (class)
• storage-bucket (method)
• (setf storage-bucket) (method)
• storage-endpoint (method)
• (setf storage-endpoint) (method)
• storage-file-url (generic function)
• store-object-in-storage (generic function)

4.1.5 mito-attachment/src/storage-components/disk.lisp

Parent

storage-components (module)

Location

src/storage/disk.lisp

Packages

mito.attachment.storage.disk

Exported Definitions

• delete-object-from-storage (method)
• disk-storage (class)
• disk-storage-bucket-directory (generic function)
• disk-storage-bucket-directory (method)
• disk-storage-directory (method)
• (setf disk-storage-directory) (method)
• disk-storage-file (generic function)
• disk-storage-file (method)
• disk-storage-mount-path (generic function)
• disk-storage-mount-path (method)
• storage-file-url (method)
• store-object-in-storage (method)
• store-object-in-storage (method)

Internal Definitions

• disk-storage-mount-path-prefix (method)
• (setf disk-storage-mount-path-prefix) (method)

4.1.6 mito-attachment/src/storage-components/s3.lisp

Parent

storage-components (module)

Location

src/storage/s3.lisp

Packages

mito.attachment.storage.s3

Exported Definitions

• delete-object-from-storage (method)
• s3-storage (class)
• s3-storage-access-key (method)
• (setf s3-storage-access-key) (method)
• s3-storage-secret-key (method)
• (setf s3-storage-secret-key) (method)
• storage-file-url (method)
• store-object-in-storage (method)
• store-object-in-storage (method)

Internal Definitions

with-s3-storage (macro)

5 Packages

Packages are listed by definition order.

5.1 mito-attachment-asd

Source

mito-attachment.asd

Use List

• asdf/interface
• common-lisp

5.2 mito-attachment

Source

mito-attachment.lisp (file)

Nickname

mito.attachment

Use List

common-lisp

5.3 mito.attachment.mixin

Source

mixin.lisp (file)

Use List

common-lisp

Exported Definitions

• attachment (class)
• content (generic function)
• content (method)
• (setf content) (method)
• (setf content) (generic function)
• (setf content) (method)
• content-type (generic function)
• content-type (method)
• (setf content-type) (method)
• (setf content-type) (generic function)
• file-key (generic function)
• file-key (method)
• (setf file-key) (method)
• (setf file-key) (generic function)
• file-size (generic function)
• file-size (method)
• (setf file-size) (method)
• (setf file-size) (generic function)
• file-url (generic function)
• file-url (method)

Internal Definitions

• initialize-with-content (function)
• slurp-stream (function)

5.4 mito.attachment.storage

Source

storage.lisp (file)

Use List

common-lisp

Used By List

• mito.attachment.storage.s3
• mito.attachment.storage.disk

Exported Definitions

• *storage* (special variable)
• delete-object-from-storage (generic function)
• delete-object-from-storage (method)
• delete-object-from-storage (method)
• storage (class)
• storage-bucket (generic function)
• storage-bucket (method)
• (setf storage-bucket) (method)
• (setf storage-bucket) (generic function)
• storage-endpoint (generic function)
• storage-endpoint (method)
• (setf storage-endpoint) (method)
• (setf storage-endpoint) (generic function)
• storage-file-url (generic function)
• storage-file-url (method)
• storage-file-url (method)
• store-object-in-storage (generic function)
• store-object-in-storage (method)
• store-object-in-storage (method)
• store-object-in-storage (method)
• store-object-in-storage (method)

5.5 mito.attachment.storage.disk

Source

disk.lisp (file)

Use List

• mito.attachment.storage
• common-lisp

Exported Definitions

• disk-storage (class)
• disk-storage-bucket-directory (generic function)
• disk-storage-bucket-directory (method)
• disk-storage-directory (generic function)
• disk-storage-directory (method)
• (setf disk-storage-directory) (method)
• (setf disk-storage-directory) (generic function)
• disk-storage-file (generic function)
• disk-storage-file (method)
• disk-storage-mount-path (generic function)
• disk-storage-mount-path (method)

Internal Definitions

• disk-storage-mount-path-prefix (generic function)
• disk-storage-mount-path-prefix (method)
• (setf disk-storage-mount-path-prefix) (method)
• (setf disk-storage-mount-path-prefix) (generic function)

5.6 mito.attachment.storage.s3

Source

s3.lisp (file)

Use List

• mito.attachment.storage
• common-lisp

Exported Definitions

• s3-storage (class)
• s3-storage-access-key (generic function)
• s3-storage-access-key (method)
• (setf s3-storage-access-key) (method)
• (setf s3-storage-access-key) (generic function)
• s3-storage-secret-key (generic function)
• s3-storage-secret-key (method)
• (setf s3-storage-secret-key) (method)
• (setf s3-storage-secret-key) (generic function)

Internal Definitions

with-s3-storage (macro)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *storage*

Package

mito.attachment.storage

Source

storage.lisp (file)

6.1.2 Generic functions

Generic Function: content OBJECT

Generic Function: (setf content) NEW-VALUE OBJECT

Package

mito.attachment.mixin

Methods

Method: content (ATTACHMENT attachment)

automatically generated reader method

Source

mixin.lisp (file)

Method: (setf content) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

mixin.lisp (file)

Method: (setf content) CONTENT (ATTACHMENT attachment) after

Source

mixin.lisp (file)

Generic Function: content-type OBJECT

Generic Function: (setf content-type) NEW-VALUE OBJECT

Package

mito.attachment.mixin

Methods

Method: content-type (ATTACHMENT attachment)

automatically generated reader method

Source

mixin.lisp (file)

Method: (setf content-type) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

mixin.lisp (file)

Generic Function: delete-object-from-storage STORAGE FILE-KEY

Package

mito.attachment.storage

Source

storage.lisp (file)

Methods

Method: delete-object-from-storage (STORAGE s3-storage) FILE-KEY

Source

s3.lisp (file)

Method: delete-object-from-storage (STORAGE disk-storage) FILE-KEY

Source

disk.lisp (file)

Generic Function: disk-storage-bucket-directory STORAGE

Package

mito.attachment.storage.disk

Source

disk.lisp (file)

Methods

Method: disk-storage-bucket-directory (STORAGE disk-storage)

Generic Function: disk-storage-directory OBJECT

Generic Function: (setf disk-storage-directory) NEW-VALUE OBJECT

Package

mito.attachment.storage.disk

Methods

Method: disk-storage-directory (DISK-STORAGE disk-storage)

automatically generated reader method

Source

disk.lisp (file)

Method: (setf disk-storage-directory) NEW-VALUE (DISK-STORAGE disk-storage)

automatically generated writer method

Source

disk.lisp (file)

Generic Function: disk-storage-file STORAGE FILE-KEY

Package

mito.attachment.storage.disk

Source

disk.lisp (file)

Methods

Method: disk-storage-file (STORAGE disk-storage) FILE-KEY

Generic Function: disk-storage-mount-path STORAGE

Package

mito.attachment.storage.disk

Source

disk.lisp (file)

Methods

Method: disk-storage-mount-path (STORAGE disk-storage)

Generic Function: file-key OBJECT

Generic Function: (setf file-key) NEW-VALUE OBJECT

Package

mito.attachment.mixin

Methods

Method: file-key (ATTACHMENT attachment)

automatically generated reader method

Source

mixin.lisp (file)

Method: (setf file-key) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

mixin.lisp (file)

Generic Function: file-size OBJECT

Generic Function: (setf file-size) NEW-VALUE OBJECT

Package

mito.attachment.mixin

Methods

Method: file-size (ATTACHMENT attachment)

automatically generated reader method

Source

mixin.lisp (file)

Method: (setf file-size) NEW-VALUE (ATTACHMENT attachment)

automatically generated writer method

Source

mixin.lisp (file)

Generic Function: file-url ATTACHMENT

Package

mito.attachment.mixin

Source

mixin.lisp (file)

Methods

Method: file-url (ATTACHMENT attachment)

Generic Function: s3-storage-access-key OBJECT

Generic Function: (setf s3-storage-access-key) NEW-VALUE OBJECT

Package

mito.attachment.storage.s3

Methods

Method: s3-storage-access-key (S3-STORAGE s3-storage)

automatically generated reader method

Source

s3.lisp (file)

Method: (setf s3-storage-access-key) NEW-VALUE (S3-STORAGE s3-storage)

automatically generated writer method

Source

s3.lisp (file)

Generic Function: s3-storage-secret-key OBJECT

Generic Function: (setf s3-storage-secret-key) NEW-VALUE OBJECT

Package

mito.attachment.storage.s3

Methods

Method: s3-storage-secret-key (S3-STORAGE s3-storage)

automatically generated reader method

Source

s3.lisp (file)

Method: (setf s3-storage-secret-key) NEW-VALUE (S3-STORAGE s3-storage)

automatically generated writer method

Source

s3.lisp (file)

Generic Function: storage-bucket OBJECT

Generic Function: (setf storage-bucket) NEW-VALUE OBJECT

Package

mito.attachment.storage

Methods

Method: storage-bucket (STORAGE storage)

automatically generated reader method

Source

storage.lisp (file)

Method: (setf storage-bucket) NEW-VALUE (STORAGE storage)

automatically generated writer method

Source

storage.lisp (file)

Generic Function: storage-endpoint OBJECT

Generic Function: (setf storage-endpoint) NEW-VALUE OBJECT

Package

mito.attachment.storage

Methods

Method: storage-endpoint (STORAGE storage)

automatically generated reader method

Source

storage.lisp (file)

Method: (setf storage-endpoint) NEW-VALUE (STORAGE storage)

automatically generated writer method

Source

storage.lisp (file)

Generic Function: storage-file-url STORAGE FILE-KEY

Package

mito.attachment.storage

Source

storage.lisp (file)

Methods

Method: storage-file-url (STORAGE s3-storage) FILE-KEY

Source

s3.lisp (file)

Method: storage-file-url (STORAGE disk-storage) FILE-KEY

Source

disk.lisp (file)

Generic Function: store-object-in-storage STORAGE OBJECT FILE-KEY

Package

mito.attachment.storage

Source

storage.lisp (file)

Methods

Method: store-object-in-storage (STORAGE s3-storage) (OBJECT stream) FILE-KEY

Source

s3.lisp (file)

Method: store-object-in-storage (STORAGE s3-storage) (OBJECT pathname) FILE-KEY

Source

s3.lisp (file)

Method: store-object-in-storage (STORAGE disk-storage) (OBJECT stream) FILE-KEY

Source

disk.lisp (file)

Method: store-object-in-storage (STORAGE disk-storage) (OBJECT pathname) FILE-KEY

Source

disk.lisp (file)

6.1.3 Classes

Class: attachment ()

Package

mito.attachment.mixin

Source

mixin.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• delete-dao (method)
• save-dao (method)
• file-url (method)
• (setf content) (method)
• initialize-instance (method)
• content (method)
• content (method)
• file-size (method)
• file-size (method)
• content-type (method)
• content-type (method)
• file-key (method)
• file-key (method)

Direct slots

Slot: file-key

Initargs

:file-key

Readers

file-key (generic function)

Writers

(setf file-key) (generic function)

Slot: content-type

Initargs

:content-type

Readers

content-type (generic function)

Writers

(setf content-type) (generic function)

Slot: file-size

Initargs

:file-size

Readers

file-size (generic function)

Writers

(setf file-size) (generic function)

Slot: content

Initargs

:content

Readers

content (generic function)

Writers

(setf content) (generic function)

Class: disk-storage ()

Package

mito.attachment.storage.disk

Source

disk.lisp (file)

Direct superclasses

• lack-component (class)
• storage (class)

Direct methods

• call (method)
• delete-object-from-storage (method)
• store-object-in-storage (method)
• store-object-in-storage (method)
• storage-file-url (method)
• disk-storage-mount-path (method)
• disk-storage-file (method)
• disk-storage-bucket-directory (method)
• disk-storage-mount-path-prefix (method)
• disk-storage-mount-path-prefix (method)
• disk-storage-directory (method)
• disk-storage-directory (method)

Direct slots

Slot: directory

Initargs

:directory

Readers

disk-storage-directory (generic function)

Writers

(setf disk-storage-directory) (generic function)

Slot: mount-path-prefix

Initargs

:mount-path-prefix

Readers

disk-storage-mount-path-prefix (generic function)

Writers

(setf disk-storage-mount-path-prefix) (generic function)

Class: s3-storage ()

Package

mito.attachment.storage.s3

Source

s3.lisp (file)

Direct superclasses

storage (class)

Direct methods

• delete-object-from-storage (method)
• store-object-in-storage (method)
• store-object-in-storage (method)
• storage-file-url (method)
• s3-storage-secret-key (method)
• s3-storage-secret-key (method)
• s3-storage-access-key (method)
• s3-storage-access-key (method)

Direct slots

Slot: access-key

Initargs

:access-key

Readers

s3-storage-access-key (generic function)

Writers

(setf s3-storage-access-key) (generic function)

Slot: secret-key

Initargs

:secret-key

Readers

s3-storage-secret-key (generic function)

Writers

(setf s3-storage-secret-key) (generic function)

Direct Default Initargs

Initarg	Value
:endpoint	zs3:*s3-endpoint*

Class: storage ()

Package

mito.attachment.storage

Source

storage.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• disk-storage (class)
• s3-storage (class)

Direct methods

• storage-endpoint (method)
• storage-endpoint (method)
• storage-bucket (method)
• storage-bucket (method)

Direct slots

Slot: bucket

Initargs

:bucket

Readers

storage-bucket (generic function)

Writers

(setf storage-bucket) (generic function)

Slot: endpoint

Initargs

:endpoint

Readers

storage-endpoint (generic function)

Writers

(setf storage-endpoint) (generic function)

6.2 Internal definitions

6.2.1 Macros

Macro: with-s3-storage STORAGE &body BODY

Package

mito.attachment.storage.s3

Source

s3.lisp (file)

6.2.2 Functions

Function: initialize-with-content ATTACHMENT CONTENT

Package

mito.attachment.mixin

Source

mixin.lisp (file)

Function: slurp-stream STREAM &optional SIZE

Package

mito.attachment.mixin

Source

mixin.lisp (file)

6.2.3 Generic functions

Generic Function: disk-storage-mount-path-prefix OBJECT

Generic Function: (setf disk-storage-mount-path-prefix) NEW-VALUE OBJECT

Package

mito.attachment.storage.disk

Methods

Method: disk-storage-mount-path-prefix (DISK-STORAGE disk-storage)

automatically generated reader method

Source

disk.lisp (file)

Method: (setf disk-storage-mount-path-prefix) NEW-VALUE (DISK-STORAGE disk-storage)

automatically generated writer method

Source

disk.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types