Merge pull request #114 from MainframeHQ/swarm-v05

Swarm v0.5

.travis.yml

@@ -20,11 +20,11 @@ matrix:
         - ./start_swarm_node.sh -d
     - os: osx
       env:
-        - SWARM_VERSION=swarm-darwin-amd64-0.4.3-66e016c6
+        - SWARM_VERSION=swarm-darwin-amd64-0.5.0-c1c233d1
       before_install:
         - mkdir ~/data && echo "password" > ~/password
         - curl "https://ethswarm.blob.core.windows.net/builds/$SWARM_VERSION.tar.gz" | tar -x
-        - ./$SWARM_VERSION/swarm --datadir ~/data --password ~/password --nosync --maxpeers=0 --verbosity=0 --httpaddr=0.0.0.0 --nat=none --corsdomain="*" --ws --wsaddr=0.0.0.0 --wsorigins="*" &
+        - ./$SWARM_VERSION/swarm --datadir ~/data --password ~/password --maxpeers=0 --verbosity=0 --httpaddr=0.0.0.0 --nat=none --corsdomain="*" --ws --wsaddr=0.0.0.0 --wsorigins="*" --enable-pinning &
 
 script:
   - yarn build

CHANGELOG.md

@@ -1,3 +1,30 @@
+## v0.10.0 (unreleased)
+
+### Breaking changes
+
+- The [`PollOptions` interface of the Bzz API](https://erebos.js.org/docs/api-bzz#polloptions) has been changed and is now used by the [Timeline API](https://erebos.js.org/docs/timeline-api). The [`PollFeedOptions` interface](https://erebos.js.org/docs/api-bzz#pollfeedoptions) is now used for polling feeds.
+- The `PollOptions` interface of the Timeline API has been removed, now using the interface exported by the Bzz API.
+
+### Swarm v0.5 support
+
+Erebos v0.10 adds support for 2 new features added to the [Swarm v0.5 release](https://www.reddit.com/r/ethswarm/comments/dbqcbv/swarm_v050_is_released/):
+
+#### [Pinning content](https://swarm-guide.readthedocs.io/en/latest/dapp_developer/index.html#pinning-content)
+
+- Using the [`pin()`](https://erebos.js.org/docs/api-bzz#pin), [`unpin()`](https://erebos.js.org/docs/api-bzz#unpin) and [`pins()`](https://erebos.js.org/docs/api-bzz#pins) methods of the [Bzz class](https://erebos.js.org/docs/api-bzz#bzz-class).
+- Using the [`pin` option](https://erebos.js.org/docs/api-bzz#uploadoptions) when uploading content.
+- Using the [CLI](cli.md#pin-commands).
+
+#### [Tags](https://swarm-guide.readthedocs.io/en/latest/dapp_developer/index.html#tags)
+
+It is possible to track progress of chunks spreading over the network using the [`getTag()`](https://erebos.js.org/docs/api-bzz#gettag) and [`pins()`](https://erebos.js.org/docs/api-bzz#polltag) methods of the [Bzz class](https://erebos.js.org/docs/api-bzz#bzz-class).
+
+### New packages
+
+RPC utility libraries that were previously stored in a different repository have now been moved to the Erebos repository and npm organization.
+
+You can learn more about these tools in the [added documentation](https://erebos.js.org/docs/rpc-intro).
+
 ## v0.9.0 (2019-08-12)
 
 ### Breaking changes

__tests__/api-bzz-node.ts

@@ -688,4 +688,93 @@ describe('api-bzz-node', () => {
     // Test should timeout if the trigger is not executed
     trigger.next()
   })
+
+  it('checks if pinning is enabled', async () => {
+    const enabled = await bzz.pinEnabled()
+    expect(enabled).toBe(true)
+  })
+
+  it('pins when uploading', async () => {
+    const pinsBefore = await bzz.pins()
+    await Promise.all(pinsBefore.map(p => bzz.unpin(p.address)))
+
+    const hash = await bzz.uploadFile(uploadContent, { pin: true })
+    const pins = await bzz.pins()
+    expect(pins.length).toBe(1)
+    expect(pins[0]).toEqual({
+      address: hash,
+      counter: 1,
+      raw: true,
+      size: uploadContent.length,
+    })
+
+    await bzz.unpin(hash)
+    const pinsAfter = await bzz.pins()
+    expect(pinsAfter.length).toBe(0)
+  })
+
+  it('pins an already uploaded raw file', async () => {
+    const pinsBefore = await bzz.pins()
+    await Promise.all(pinsBefore.map(p => bzz.unpin(p.address)))
+
+    const hash = await bzz.uploadFile(uploadContent)
+    await bzz.pin(hash, { raw: true })
+
+    const pins = await bzz.pins()
+    expect(pins.length).toBe(1)
+    expect(pins[0]).toEqual({
+      address: hash,
+      counter: 1,
+      raw: true,
+      size: uploadContent.length,
+    })
+
+    await bzz.unpin(hash)
+    const pinsAfter = await bzz.pins()
+    expect(pinsAfter.length).toBe(0)
+  })
+
+  it('pins a manifest', async () => {
+    const pinsBefore = await bzz.pins()
+    await Promise.all(pinsBefore.map(p => bzz.unpin(p.address)))
+
+    const hash = await bzz.uploadFile(uploadContent, {
+      contentType: 'text/plain',
+    })
+    await bzz.pin(hash)
+
+    const pins = await bzz.pins()
+    expect(pins.length).toBe(1)
+    expect(pins[0].address).toBe(hash)
+    expect(pins[0].raw).toBe(false)
+
+    await bzz.unpin(hash)
+    const pinsAfter = await bzz.pins()
+    expect(pinsAfter.length).toBe(0)
+  })
+
+  it('gets an upload tag', async () => {
+    const hash = await bzz.uploadFile(uploadContent, {
+      contentType: 'text/plain',
+    })
+    const tag = await bzz.getTag(hash)
+    expect(tag.address).toBe(hash)
+  })
+
+  it('polls an upload tag', async done => {
+    const hash = await bzz.uploadFile(uploadContent, {
+      contentType: 'text/plain',
+    })
+
+    let count = 0
+    const sub = bzz.pollTag(hash, { interval: 300 }).subscribe({
+      next: tag => {
+        expect(tag.address).toBe(hash)
+        if (count++ === 3) {
+          sub.unsubscribe()
+          done()
+        }
+      },
+    })
+  })
 })

docs/api-bzz.md

@@ -155,6 +155,7 @@ interface UploadOptions extends FileOptions {
   defaultPath?: string
   encrypt?: boolean
   manifestHash?: hexValue | string
+  pin?: boolean
   size?: number
 }
 ```
@@ -167,27 +168,77 @@ Extends [FetchOptions](#fetchoptions)
 interface PollOptions extends FetchOptions {
   interval: number // in milliseconds
   immediate?: boolean // defaults to true
+}
+```
+
+### PollFeedOptions
+
+Extends [PollOptions](#polloptions)
+
+```typescript
+interface PollFeedOptions extends PollOptions {
   whenEmpty?: 'accept' | 'ignore' | 'error' // defaults to 'accept'
   trigger?: Observable<void>
 }
 ```
 
-### PollContentHashOptions
+### PollFeedContentHashOptions
 
-Extends [PollOptions](#polloptions)
+Extends [PollFeedOptions](#pollfeedoptions)
 
 ```typescript
-interface PollContentHashOptions extends PollOptions {
+interface PollFeedContentHashOptions extends PollFeedOptions {
   changedOnly?: boolean
 }
 ```
 
-### PollContentOptions
+### PollFeedContentOptions
+
+Extends [DownloadOptions](#downloadoptions) and [PollFeedContentHashOptions](#pollfeedcontenthashoptions)
+
+```typescript
+interface PollFeedContentOptions
+  extends DownloadOptions,
+    PollFeedContentHashOptions {}
+```
+
+### PinOptions
 
-Extends [DownloadOptions](#downloadoptions) and [PollContentHashOptions](#pollcontenthashoptions)
+Extends [FetchOptions](#fetchoptions)
 
 ```typescript
-interface PollContentOptions extends DownloadOptions, PollContentHashOptions {}
+interface PinOptions extends FetchOptions {
+  download?: boolean
+  raw?: boolean
+}
+```
+
+### PinnedFile
+
+```typescript
+interface PinnedFile {
+  address: string
+  counter: number
+  raw: boolean
+  size: number
+}
+```
+
+### Tag
+
+```typescript
+interface Tag {
+  uid: number
+  name: string
+  address: string
+  total: number
+  split: number
+  seen: number
+  stored: number
+  sent: number
+  synced: number
+  startedAt: Date
+}
 ```
 
 ### FeedParams
@@ -268,8 +319,6 @@ interface BzzConfig {
 
 ### Bzz class
 
-_Exported as `BzzBrowser` by `@erebos/api-bzz-browser` and `BzzNode` by `@erebos/api-bzz-node`._
-
 **Arguments**
 
 1.  [`config: BzzConfig`](#bzzconfig), see below
@@ -314,6 +363,17 @@ Returns the Swarm URL for a feed based on the provided arguments.
 
 **Returns** `string`
 
+### .getPinURL()
+
+Returns the Swarm URL for a pin based on the provided arguments.
+
+**Arguments**
+
+1.  `hash?: string`: hash of the resource
+1.  `raw: boolean = false`
+
+**Returns** `string`
+
 ### .hash()
 
 Returns the hash of the provided `domain`.
@@ -423,18 +483,18 @@ Deletes the resource with at the provided `path` in the manifest and returns the
 
 ### .getFeedContentHash()
 
-Returns the feed contents hash, or `null` if not found.
+Returns the feed contents hash.
 
 **Arguments**
 
 1.  `hashOrParams: string | FeedParams`: : ENS name, hash of the feed manifest or [feed parameters](#feedparams)
 1.  [`options?: FetchOptions = {}`](#fetchoptions)
 
-**Returns** `Promise<hexValue | null>`
+**Returns** `Promise<string>`
 
 ### .getFeedContent()
 
-Returns the feed contents `Response`, or `null` if not found.
+Returns the feed contents `Response`.
 
 **Arguments**
 
@@ -501,7 +561,7 @@ Returns a [RxJS `Observable`](https://rxjs.dev/api/index/class/Observable) emitt
 **Arguments**
 
 1.  [`meta: FeedMetadata`](#feedmetadata)
-1.  `data: string | Object | Buffer`
+1.  `data: string | Record<string, any> | Buffer`
 1.  [`options?: FetchOptions = {}`](#fetchoptions)
 1.  `signParams?: any`
 
@@ -512,7 +572,7 @@ Returns a [RxJS `Observable`](https://rxjs.dev/api/index/class/Observable) emitt
 **Arguments**
 
 1.  `hashOrParams: string | FeedParams`: ENS name, hash of the feed manifest or [feed parameters](#feedparams)
-1.  `data: string | Object | Buffer`
+1.  `data: string | Record<string, any> | Buffer`
 1.  [`options?: FetchOptions = {}`](#fetchoptions)
 1.  `signParams?: any`
 
@@ -536,15 +596,65 @@ This method implements the flow of uploading the provided `data` and updating th
 **Arguments**
 
 1.  `hashOrParams: string | FeedParams`: ENS name, hash of the feed manifest or [feed parameters](#feedparams)
-1.  `data: string | Object | Buffer`
+1.  `data: string | Record<string, any> | Buffer`
 1.  [`options?: UploadOptions = {}`](#uploadoptions)
 1.  `signParams?: any`
 
 **Returns** `Promise<string>`
 
+### .pin()
+
+Pins the specified resource. To make sure the resource is available on the node, the `download` option can be set to explicitely download it before pinning.
+
+**Arguments**
+
+1.  `hashOrDomain: string`: ENS name or Swarm hash
+1.  [`options?: PinOptions = {}`](#pinoptions)
+
+**Returns** `Promise<void>`
+
+### .unpin()
+
+**Arguments**
+
+1.  `hashOrDomain: string`: ENS name or Swarm hash
+1.  [`options?: FetchOptions = {}`](#fetchoptions)
+
+**Returns** `Promise<void>`
+
+### .pins()
+
+Returns the list of resources currently pinned on the node.
+
+**Arguments**
+
+1.  [`options?: FetchOptions = {}`](#fetchoptions)
+
+**Returns** `Promise<Array<PinnedFile>>` the list of [`PinnedFile`](#pinnedfile)
+
+### .getTag()
+
+**Arguments**
+
+1.  `hash: string`
+1.  [`options: FetchOptions`](#fetchoptions)
+
+**Returns** `Promise<Tag>` the [`Tag`](#tag) of the given `hash`
+
+### .pollTag()
+
+Returns a [RxJS `Observable`](https://rxjs.dev/api/index/class/Observable) emitting the [`Tag`](#tag) of the given `hash`.
+
+**Arguments**
+
+1.  `hash: string`
+1.  [`options: PollOptions`](#polloptions)
+
+**Returns** `Observable<Tag>`
+
 ## Node-specific APIs
 
-_The following `BzzNode` class methods are only available when using `@erebos/api-bzz-node`._
+_The following `Bzz` class methods are only available when using `@erebos/api-bzz-node`._
 
 ### .downloadObservable()